Openapi generator: Central defintion of error response description and content

[PhilippKemkes]

In my project, I automatically generated the openapi.yaml from the Java classes. But to achieve this I have repeated annotations like

@APIResponse(responseCode = "400", description = "a description",
            content = @Content(mediaType = MediaType.APPLICATION_JSON, schema = @Schema(implementation = ErrorMessage.class)))

@APIResponse(responseCode = "401", description = "another description")

again and again for all endpoints. For most endpoints, the description and content depend only on the error code.
Is there a way to define the content and description only once per error code so that the generated openapi.yaml still contains them for all endpoints?

Of course it should still be possible to set individual values for responseCode = "200".

[quarkus-bot[bot]]

/cc @EricWittmann (openapi), @MikeEdgar (openapi), @phillip-kruger (openapi)

[MikeEdgar]

@PhilippKemkes you can use the @OpenAPIDefinition annotation, which has a components.responses array to define your @APIResponses. @OpenAPIDefinition should be placed in a package-info.java or on a JAX-RS Application class in order to be found by the scanner. Each @APIResponse should have a name that will be its key within components in the resulting OpenAPI.

@OpenAPIDefinition(
  components = @Components(
    responses = {
      @APIResponse(
        name = "BadRequest",
        description = "a description",
        content = @Content(mediaType = MediaType.APPLICATION_JSON, schema = @Schema(implementation = ErrorMessage.class))),
      @APIResponse(
        name = "Unauthorized", 
        description = "another description")
    }
  )
)

Then on your resource classes or individual resource methods:

@APIResponse(responseCode = "400", ref = "BadRequest")
@APIResponse(responseCode = "401", ref = "Unauthorized")

There is still some repetition, but note you can place them at the class level to apply to all endpoints within.

[phillip-kruger]

If you use Quarkus security the 401 should be added automatically