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:
@Rest(
// 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"
)
)
@JsonSchemaConfig(
// Add descriptions to the following types when not specified:
addDescriptionsTo="bean,collection,array,map,enum",
// Add x-example to the following types:
addExamplesTo="bean,collection,array,map",
// Don't generate schema information on the Swagger bean itself or HTML beans.
ignoreTypes="Swagger,org.apache.juneau.dto.html5.*",
// Use $ref references for bean definitions to reduce duplication in Swagger.
useBeanDefs="true"
)
@BeanConfig(
// When parsing generated beans, ignore unknown properties that may only exist as getters and not setters.
ignoreUnknownBeanProperties="true",
// POJO swaps to apply to all serializers/parsers on this method.
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
}
)
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.