BasicRestServlet
Any subclass of {@link oajr.BasicRestServlet} gets an auto-generated Swagger UI when performing an OPTIONS
request with Accept:text/html
.
The underlying mechanics are simple.
The {@link oajr.BasicRestServlet#getOptions(RestRequest)} method returns a {@link oaj.dto.swagger.Swagger} bean
consisting of information gathered from annotations and other sources.
Then that bean is swapped for a {@link oaj.dto.swagger.ui.SwaggerUI} bean when rendered as HTML.
Here's the class that defines the behavior:
@RestResource(
// Allow OPTIONS requests to be simulated using ?method=OPTIONS query parameter.
allowedMethodParams="OPTIONS",
...
)
public abstract class BasicRestServlet extends RestServlet implements BasicRestConfig {
/**
* [OPTIONS /*] - Show resource options.
*
* @param req The HTTP request.
* @return A bean containing the contents for the OPTIONS page.
*/
@RestMethod(name=OPTIONS, path="/*",
summary="Swagger documentation",
description="Swagger documentation for this resource.",
htmldoc=@HtmlDoc(
// Override the nav links for the swagger page.
navlinks={
"back: servlet:/",
"json: servlet:/?method=OPTIONS&Accept=text/json&plainText=true"
},
// Never show aside contents of page inherited from class.
aside="NONE"
),
// POJO swaps to apply to all serializers/parsers.
pojoSwaps={
// Use the SwaggerUI swap when rendering Swagger beans.
// This is a per-media-type swap that only applies to text/html requests.
SwaggerUI.class
},
// Properties to apply to all serializers/parsers and REST-specific API objects.
properties={
// Add descriptions to the following types when not specified:
@Property(name=JSONSCHEMA_addDescriptionsTo, value="bean,collection,array,map,enum"),
// Add x-example to the following types:
@Property(name=JSONSCHEMA_addExamplesTo, value="bean,collection,array,map"),
// Don't generate schema information on the Swagger bean itself or HTML beans.
@Property(name=JSONSCHEMA_ignoreTypes, value="Swagger,org.apache.juneau.dto.html5.*")
},
// Shortcut for boolean properties.
flags={
// Use $ref references for bean definitions to reduce duplication in Swagger.
JSONSCHEMA_useBeanDefs
}
)
public Swagger getOptions(RestRequest req) {
// Localized Swagger for this resource is available through the RestRequest object.
return req.getSwagger();
}
}
Note that to have your resource create Swagger UI, you must either extend from {@link oajr.BasicRestServlet} or provide
your own @RestMethod-annotated method that returns a {@link oaj.dto.swagger.Swagger} object and a {@link oaj.dto.swagger.ui.SwaggerUI} swap.