We have a requirement to generate multiple definitions of an API using the Java annotations. We are open to any and all suggestions but the one proposed seemed like a viable option if we could work out how to get it to work.
We basically need to generate 2 API docs from a single code base. The first should include ALL the scanned resources. This one is no problem and we can achieve this fine.
Here is the abridged version of an example annotated method:
@POST
@Path("/some/path")
@Consumes("application/json")
@Operation(
summary = "Do something...",
description = "Do something..."
)
@Tags({@Tag(name = "example-tag")})
@RequestBody(
description = "Do something...",
required = true,
content = @Content(
schema = @Schema(
implementation = Example.class
)
)
)
@ApiResponses({
@ApiResponse(
responseCode = "201",
description = "Do something...",
content = @Content(
schema = @Schema(
implementation = Example.class
)
)
)
})
public ApiResponse doSomething() throws Exception {
...
}
And here is how we build the docs:
OpenAPI oas = new OpenAPI();
// The basic docs
Info info = new Info()
.title("...")
.description("...")
.termsOfService("...")
.contact(new Contact().email("..."))
.version("...");
// The API server
Server server = new Server().url("...");
// The authentication schemas
SecurityScheme scheme = new SecurityScheme()
.name("...")
.type(...)
.scheme("...")
.in(...);
Components components = new Components().addSecuritySchemes("example-auth", scheme)
oas.info(info);
oas.addServersItem(server);
oas.components(components);
ModelConverters instance = ModelConverters.getInstance();
instance.addConverter(new MultimapConverter());
SwaggerConfiguration oasConfig = new SwaggerConfiguration()
.openAPI(oas)
.prettyPrint(true)
.resourcePackages(Stream.of("...").collect(Collectors.toSet()));
OpenAPI openApi = new JaxrsOpenApiContextBuilder()
.openApiConfiguration(oasConfig)
.buildContext(true)
.read();
Ok so far so good. We end up with a definition that contains everything. Now we need to create a second definition. This time it needs to exclude all operations that contain the @Tag=(name = "private").
I created a filter that extended AbstractSpecFilter called TagFilter. I have overridden the implementation and then added it to the filter class of the SwaggerConfiguration:
SwaggerConfiguration oasConfig = new SwaggerConfiguration()
.openAPI(oas)
.filterClass(TagFilter.class.getName()) // Also tried getCanonicalName()
.prettyPrint(true)
.resourcePackages(Stream.of("...").collect(Collectors.toSet()));
Unfortunately the filter class is never instantiated. Not sure how else to intercept the operations to remove them. Other options that have crossed our mind is to use the @Hidden annotation if we could find a way to force one of the definitions to ignore the @Hidden.