Display response header information in API reference

[hkosova]

Which Fern component?

Fern Docs

How important is this?

P2 - Medium (Would be helpful)

What's the feature?

In OpenAPI, responses can have headers defined. This can be used, for example, to document the rate limit headers.

Currently, Fern does not display headers in the "Responses" section of endpoint reference pages.

As an API vendor and as a technical writer, I expect the response header information defined in my OpenAPI spec to be reflected in the API reference.

Sample OpenAPI spec

openapi: 3.1.0
info:
  title: Response headers
  version: 0.0.1
paths:
  /foo:
    get:
      summary: Get a foo
      responses:
        "200":
          description: OK
        "429":
          $ref: '#/components/responses/429TooManyRequests'

components:
  responses:
    429TooManyRequests:
      description: API rate limit has been exceeded. Check the response headers for the rate limit information.
      content:
        application/json:
          example:
            message: API rate limit exceeded
      headers:
        RateLimit-Limit:
          description: The number of requests allowed per second. Same as `X-RateLimit-Limit-Second`.
          schema:
            type: integer
            examples:
              - 30
        RateLimit-Remaining:
          description: The number of available requests remaining in the current second. Same as `X-RateLimit-Remaining-Second`.
          schema:
            type: integer
            examples:
              - 0
        RateLimit-Reset:
          description: The time remaining, in seconds, until the rate limit quota is reset. Usually 1 second.
          schema:
            type: integer
            examples:
              - 1
        Retry-After:
          description: How many seconds the client should wait before making a follow-up request.
          schema:
            type: integer
            examples:
              - 1
        X-RateLimit-Limit-Second:
          description: The number of requests allowed per second. Same as `RateLimit-Limit`.
          schema:
            type: integer
            examples:
              - 30
        X-RateLimit-Remaining-Second:
          description: The number of available requests remaining in the current second. Same as `RateLimit-Remaining`.
          schema:
            type: integer
            examples:
              - 0

Additional context

How other OpenAPI renderers display response header info:

• Redoc
• Stoplight Elements
• Bump.sh
• Swagger UI

Any alternatives?

n/a

Are you interested in contributing this feature?

No