@Body
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}
- {@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.
// 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):
-
{@link java.io.Reader}
@Body annotation is optional.
Content-Type
is ignored.
-
{@link java.io.InputStream}
@Body annotation is optional.
Content-Type
is ignored.
-
Any {@doc PojoCategories Parsable POJO} type.
Content-Type
is required to identify correct parser.
-
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.
-
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.
-
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.
// 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.
// 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}