Parameters
Expanding operations shows you a list of parameters:
Parameter information can be defined in a couple of ways. The typical way is through annotations on parameters
being passed to your @RestMethod-annotated method, like so:
@RestMethod(
...
)
public Collection<Pet> getPets(
@Query(
name="s",
description={
"Search.",
"Key/value pairs representing column names and search tokens.",
"'*' and '?' can be used as meta-characters in string fields.",
"'>', '>=', '<', and '<=' can be used as limits on numeric and date fields.",
"Date fields can be matched with partial dates (e.g. '2018' to match any date in the year 2018)."
},
type="array",
collectionFormat="csv",
example="Bill*,birthDate>2000"
)
String[] s,
@Query(
name="v",
description={
"View.",
"Column names to display."
},
type="array",
collectionFormat="csv",
example="name,birthDate"
)
String[] v,
...
) throws NotAcceptable {
...
}
Note: The type and collectionFormat values above are optional and auto-detected based on the
parameter class type if omitted. They're included here for clarity.
The examples will be explained in the next section.
Another option is to specify your parameter information in the parameters annotation as free-form Simple JSON.
In the case of the PetStoreResource.getPets() method, we pull this information from a static field
defined in the {@link oajr.converters.Queryable} class:
@RestMethod(
name=GET,
path="/pet",
summary="All pets in the store",
swagger=@MethodSwagger(
tags="pet",
parameters={
Queryable.SWAGGER_PARAMS
}
),
...
converters={Queryable.class}
)
public Collection<Pet> getPets() throws NotAcceptable {
return store.getPets();
}
public class Queryable implements RestConverter {
public static final String SWAGGER_PARAMS=""
+ "{"
+ "in:'query',"
+ "name:'s',"
+ "description:'"
+ "Search.\n"
+ "Key/value pairs representing column names and search tokens.\n"
+ "\\'*\\' and \\'?\\' can be used as meta-characters in string fields.\n"
+ "\\'>\\', \\'>=\\', \\'<\\', and \\'<=\\' can be used as limits on numeric and date fields.\n"
+ "Date fields can be matched with partial dates (e.g. \\'2018\\' to match any date in the year 2018)."
+ "',"
+ "type:'array',"
+ "collectionFormat:'csv',"
+ "x-examples:{example:'?s=Bill*,birthDate>2000'}"
+ "},"
+ "{"
+ "in:'query',"
+ "name:'v',"
+ "description:'"
+ "View.\n"
+ "Column names to display."
+ "',"
+ "type:'array',"
+ "collectionFormat:'csv',"
+ "x-examples:{example:'?v=name,birthDate'}"
+ "},"
...
;
}
This information could have also been defined in the Swagger JSON for the resource as well.
The parameter section contains information about the request body as well for PUT and POST methods, as shown here:
The definition of this method is shown here:
@RestMethod(
summary="Add a new pet to the store",
swagger=@MethodSwagger(
tags="pet"
)
)
public Ok postPet(
@Body(description="Pet object to add to the store") PetCreate pet
) throws IdConflict, NotAcceptable, UnsupportedMediaType {
store.create(pet);
return OK;
}
Note that the schema information on the body parameter is automatically detected if not provided.