OpenAPI Schema Part Parsing
Parameters annotated with any of the following are parsed using the registered {@link oaj.oapi.OpenApiParser} and
therefore support OpenAPI syntax and validation:
- {@link oaj.http.annotation.Header}
- {@link oaj.http.annotation.Query}
- {@link oaj.http.annotation.FormData}
- {@link oaj.http.annotation.Path}
- {@link oaj.http.annotation.Body} (Content-Type must match "text/openapi")
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") in a query parameter can be converted to a 2-dimensional array of Longs:
@RestMethod(method="GET", path="/testQuery")
public void testQuery(
@Query(
name="queryParamName",
collectionFormat="pipes",
items=@SubItems(
collectionFormat="csv",
type="integer",
format="int64",
minimum="0",
maximum="100"
minLength=1,
maxLength=10
),
minLength=1,
maxLength=10
)
Long[][] queryParameter
) {...}
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.
The following shows the same for a request body:
@RestMethod(method="POST", path="/testBody")
public void testBody(
@Body(
parsers=OpenApiParser.class,
defaultContentType="text/openapi",
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
) {...}
The list of valid POJO types for parameters depends on type and format of the value or items/entries of the value.
For example, instead of Longs in the example above, we could also define a 2-dimensional array of POJOs convertible from Longs:
@RestMethod(method="POST", path="/2dLongArray")
public void testBody(@Body(...) MyPojo[][] body) {...}
// POJO convertible from a Long.
public class MyPojo {
public MyPojo(Long input) {...}
}
Or even POJOs that take in arrays of Longs[]:
@RestMethod(method="POST", path="/2dLongArray")
public void testBody(@Body(...) MyPojo[] body) {...}
// POJO convertible from a Long[].
public class MyPojo {
public MyPojo(Long[] input) {...}
}
Or even POJOs that take in the whole 2-dimensional array:
@RestMethod(method="POST", path="/2dLongArray")
public void testBody(@Body(...) MyPojo body) {...}
// POJO convertible from a Long[][].
public class MyPojo {
public MyPojo(Long[][] input) {...}
}
As you can see, the complexity of possible input types expands significantly.
For more information about valid parameter types, see {@doc OpenApiParsers OpenAPI Parsers}