Getting parameter or header definition into component section so it can be re-used

Question

In OpenAPI Spec 3.0, there is a components section where you can define headers,links, schemas etc and then reuse them for various operations.

components:
  # Reusable schemas (data models)
  schemas:
    ...
  # Reusable path, query, header and cookie parameters
  parameters:
    ...
  # Security scheme definitions (see Authentication)
  securitySchemes:
    ...
  # Reusable request bodies
  requestBodies:
    ...
  # Reusable responses, such as 401 Unauthorized or 400 Bad Request
  responses:
    ...
  # Reusable response headers
  headers:

  //...

I have a number of headers that are common across various operations so it makes sense, from an open API perspective they are defined in the components section s so they can be re-used.

In Swagger, when you use @Schema it will be end up in components / schema section, but I am struggling to see how you can get a parameter or header into the components section so they can be reused.

(Note: I am using jax-rs / Jersey)

I wrote a YAML that has a header and parameter defined in components / schema an then generated the Java JAX-RS / Jersey from that but it defined the header and parameter for very API Operation. There was no re-use. It was also missing the description for header I had defined in components / header in the YAML.

Looking at the JDoc: http://docs.swagger.io/swagger-core/v2.0.8/apidocs/index.html?io/swagger/v3/oas/annotations/OpenAPIDefinition.html

It says (for header, that I use the ref attribute to refer to something in the components section, but the question is how do I get it into the components section)

Any help appreciated.

Do you mean "How to define reusable components using Java annotations"? (e.g. in Springfox) — Helen
Should have said using Jersey / JAX_RS, I'll update question — More Than Five

Ariel Carrera Ariel Carrera · Accepted Answer · 2019-08-19T04:41:47

For now, only "schemas" and "securitySchemes can be defined via Java annotations.

Btw, as a workaround, you can define global components in a YAML spec file and merge it with the annotation-driven specs at runtime.

Take a look to this issue of "Swagger" that talks about "components/parameter" section.

issue 3021

and issue 2625

Getting parameter or header definition into component section so it can be re-used

1 Answers