I am developing REST API using quarkus-rest
implamentation of Jakarta REST (formerly known as JAX-RS). I also use quarkus-smallrye-openapi
extension to generate my API specification (OpenAPI v3).
How can I fill in the fields: summary and description of an Path Item Object using annotations or otherwise (without manual specification writing)?
There isn’t really a way to do this using the standard annotations. You have a couple of options involving the static OpenAPI file or implementing an OASFilter
to add the summary and/or description.
Static OpenAPI
Placing an openapi.yaml
or openapi.json
in META-INF
(within src/main/resources
for Maven projects), you can define just the paths
and their descriptions that you care about. This file will be merged with the result of the annotation scanning.
paths:
/foo:
summary: ...,
description: ...
/foo/{bar}:
summary: ...,
description: ...
OASFilter
Implementation
Write an implementation of org.eclipse.microprofile.openapi.OASFilter
and configure it by setting the fully-qualified class name as the value of property mp.openapi.filter
. You can override method filterPathItem
with whatever logic you want to set the properties. For example, you could look them up from config properties by first obtaining a Config
from the ConfigProvider
.
class MyFilter implements OASFilter {
@Override
public PathItem filterPathItem(PathItem pathItem) {
// Logic to set the summary or description on pathItem goes here.
return pathItem;
}
}
You can do something like this with annotations:
@GET
@Path("options/{foo}")
public Response getFoo(
@Schema(description = "some desc.",required = true)
@PathParam("foo") String foo
) {
....
or you can merge/extend/enrich the generated openapi spec by putting an openapi.yaml in resources/META-INF.
On path items do this:
@GET
@Path("search")
@Operation(operationId = "SearchFoo", summary = "Search Foos", description = "Search Foos by status and date")
public Foo searchFoo...
2