Redocly / Redocly/redocly-cli

Extend Respect to check defined `response` headers to matches what is defined in the provided OpenAPI description

Open
#2,287 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

p3 Respect Type: Enhancement
Dominant language
TypeScript
Stars
1.5k
Forks
228
Avg merge
1d 14h
Merged PRs (30d)
48

Description

Is your feature request related to a problem? Please describe.
In OpenAPI descriptions it is possible to describe response headers, like in this example:

      responses:
        '200':
          description: successful operation
          headers:
            X-Rate-Limit:
              description: calls per hour allowed by the user
              schema:
                type: integer
                format: int32
            X-Expires-After:
              description: date in UTC when token expires
              schema:
                type: string
                format: date-time

Sometimes API do not return the response headers that are described in OpenAPI document, this can happen due to API issue, or when developer is working with mock APIs.

Respect already perform schema validation for described response body by default in case Step is connected to OpenAPI operation.

Image

Describe the solution you'd like

  • Introduce the new check to Respect, called RESPONSE_HEADER_CHECK and validate Step response headers to match OpenAPI description when Step is connected to operation by using operationId.
    Response can contain some extra headers, this should be ok. But it must include required headers described in OpenAPI spec.
  • Make this check to be configurable with severity cli options.

So if, for example OpenAPI response contains required headers, Respect should check thatX-Request-ID and X-Rate-Limit-Remaining were returned from API.

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
paths:
  /items:
    get:
      summary: Get items
      responses:
        '200':
          description: Successful response
          headers:
            X-Request-ID:
              description: Correlation ID for the request
              required: true
              schema:
                type: string
            X-Rate-Limit-Remaining:
              description: Requests remaining in the current rate limit window
              required: false
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

Describe alternatives you've considered

Do nothing.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with Respect’s existing response-body schema validation for steps linked to OpenAPI operations by operationId, then trace how response headers and severity CLI options are handled. Implement the RESPONSE_HEADER_CHECK so required headers are detected, optional or extra headers remain valid, and severity is configurable. Done means missing required headers are reported while valid responses pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.