javaswaggerjax-rsquarkusopenapi

Summary and description for the Path Item Object of OpenAPI

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)?

Solution

  • 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;
    }
}