The {@link oaj.http.annotation.Body @Body} annotation is used to identify POJOs to be used as the body of an HTTP request.

• {@link oaj.http.annotation.Body Body}
  • {@link oaj.http.annotation.Body#api() api} - Free-form Swagger JSON.
  • {@link oaj.http.annotation.Body#description() description} - Description.
  • {@link oaj.http.annotation.Body#example() example} - Serialized example.
  • {@link oaj.http.annotation.Body#examples() examples} - Serialized examples per media type.
  • {@link oaj.http.annotation.Body#required() required} - Input validation. Body must be present.
  • {@link oaj.http.annotation.Body#schema() schema} - Swagger schema.
  • {@link oaj.http.annotation.Body#value() value} - Free-form Swagger JSON.

Examples:

// Defined on parameter @RestMethod(name=POST) public void addPet(@Body Pet pet) {...}

// Defined on POJO class @RestMethod(name=POST) public void addPet(Pet pet) {...} @Body public class Pet {...}

This is functionally equivalent to the following code:

@RestMethod(name=POST) public void addPet(RestRequest req) { Person person = req.getBody().asType(Pet.class); ... }

Any of the following types can be used for the parameter or POJO class (matched in the specified order):

1. {@link java.io.Reader}
   @Body annotation is optional.
   Content-Type is ignored.
2. {@link java.io.InputStream}
   @Body annotation is optional.
   Content-Type is ignored.
3. Any {@doc PojoCategories Parsable POJO} type.
   Content-Type is required to identify correct parser.
4. Objects convertible from {@link java.io.Reader} by having one of the following non-deprecated methods:
   • public T(Reader in) {...}
   • public static T create(Reader in) {...}
   • public static T fromReader(Reader in) {...}
   Content-Type must not be present or match an existing parser so that it's not parsed as a POJO.
5. Objects convertible from {@link java.io.InputStream} by having one of the following non-deprecated methods:
   • public T(InputStream in) {...}
   • public static T create(InputStream in) {...}
   • public static T fromInputStream(InputStream in) {...}
   Content-Type must not be present or match an existing parser so that it's not parsed as a POJO.
6. Objects convertible from {@link java.lang.String} by having one of the following non-deprecated methods:
   • public T(String in) {...}
   • public static T create(String in) {...}
   • public static T fromString(String in) {...}
   • public static T parse(String in) {...}
   • public static T parseString(String in) {...}
   • public static T forName(String in) {...}
   • public static T forString(String in) {...}
   Note that this also includes all enums.

The {@link oaj.oapi.OpenApiSerializer} class can be used to serialize HTTP bodies to OpenAPI-based output.

For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9") can be converted to a 2-dimensional array of Longs:

// Body is a pipe-delimited list of comma-delimited lists of longs. @RestMethod( method="POST", path="/testBody", serializers=OpenApiSerializers.class, defaultAccept="text/openapi" ) public void testBody( @Body( schema=@Schema( items=@Items( collectionFormat="pipes", items=@SubItems( collectionFormat="csv", type="integer", format="int64", minimum="0", maximum="100" minLength=1, maxLength=10 ) ), minLength=1, maxLength=10 ) ) Long[][] body ) {...}

Input will be converted based on the types and formats defined in the schema definition.
Input validations such as minLength/maxLength that don't match the input will result in automatic 400 Bad Request responses.

For more information about valid parameter types when using OpenAPI parsing, see {@doc juneau-marshall.OpenApiDetails.Parsers OpenAPI Parsers}

The @Body annotation is also used for supplying swagger information about the body of the request.
This information is used to populate the auto-generated Swagger documentation and UI.

Examples:

// Normal @Body( description="Pet object to add to the store", required=true, example="{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}" )

// Free-form // Note the extra field @Body({ "description: 'Pet object to add to the store',", "required: true,", "example: {name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}," "x-extra: 'extra field'" })

{@doc DefaultRestSvlVariables} (e.g. "$L{my.localized.variable}") are supported on annotation fields.

Example:

// Localized @Body( description="$L{PetObjectDescription}" )

Other Notes:

• Annotation parameter values will be aggregated when used on POJO parent and child classes.
  Values on child classes override values on parent classes.
• Annotation parameter values will be aggregated when used on both POJOs and REST methods.
  Values on methods override values on POJO classes.

See Also:

• {@link oajr.RequestBody}
• {@doc juneau-rest-server.OpenApiSchemaPartParsing}