Document X-RateLimit headers in the schema

[weppos]

We have a number of mismatching/undocumented headers in our OpenAPI schema file:

Truth to be told, our API returns more header than necessary (as we bundle some with the app as well). But that's a different conversation.

At minimum, for API-specific headers (like X-RateLimit), we should have them documented in the schema file.

[weppos]

/cc @DXTimer

[DXTimer]

I've added this to our board to look into during this cycle.

[DXTimer]

There is no elegant way to add headers to the spec it has to be done for each response. If we were to go ahead we would be adding approximately 400 new lines to document just the rate limit headers. It's not very common to document common headers. Would you still like to see the headers added to the spec?

To give an idea of what it looks like to document the headers:

openapi: 3.0.1
info:
  title: API
  version: 1.0.0
paths:
  /:
    get:
      responses:
        '200':
          description: Successful Request
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
          headers:
            'X-Total-Items':
               $ref: '#/components/headers/xTotalItems'
            'X-Total-Pages':
               $ref: '#/components/headers/xTotalPages'
components:
  schemas:
    User: {}
  headers:
    xTotalItems:
      schema:
        type: integer
        description: test
    xTotalPages:
      schema:
        type: integer
        description: test

[weppos]

Given the complexity, at this time I don't think we want to move forward. i recommend we reach out to the OpenAPI maintainers and file a enhancement request to define a reusable component as exists for other schema objects, then we close this one.

[DXTimer]

It seems unlikely that OAS 3.x will incorporate support for headers as reference objects, given the primary focus on OAS 4, also known as Moonwalk. One potential workaround is to leverage YAML anchors to define shared headers. In this approach, maintainers would be responsible for rendering the YAML, applying the anchors, and generating a valid OpenAPI schema. This schema would be treated as read-only by the maintainers and publicly shared and referenced as needed.

openapi: 3.0.1
info:
  title: API
  version: 1.0.0
paths:
  /:
    get:
      responses:
        '200':
          description: Successful Request
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
          headers: *commonHeaders

components:
  schemas:
    User: {}

commonHeaders: &commonHeaders
    xTotalItems:
      schema:
        type: integer
        description: test
    xTotalPages:
      schema:
        type: integer
        description: test

Closing for now. If we choose to take any of the mentioned approaches we can revisit the issue.