Cannot generate global `parameters` node using Java annotations

I have a bunch of JAX-RS 2.0 interfaces that define my API. I’m using Swagger 2.0 annotations to produce an OpenAPI 3.0 spec.

Many of the operations in the API share certain query and header parameters (things like language, client version, etc). It would be incredibly excessive and a nightmare to maintain if we just copied and pasted these shared parameters onto each operation.

Ideally, we’d like to blanket apply all of these parameters to our operations, but there doesn’t seem to be support for that in OpenAPI 3.0. The orthodox way to do this seems to be to use $ref to refer to parameters defined at the global API level.

There doesn’t seem to be any way to produce that global parameters node using just Swagger annotations, though. Is this a gap in functionality, or am I missing how to do this?

As an implementation, I’d expect to see a parameters field in the @OpenAPIDefinition annotation.

[andreaangiolillo]

+1 on the addition of @Components

[catbref]

Looking at the OpenAPI v3.0 spec it might be better, or even easier, to add a @Components annotation for use inside @OpenAPIDefinition. Then inside @Components any number of @Parameter or @Schema or anything else as mentioned here: https://swagger.io/specification/#componentsObject

[Edit: quoting annotations]