[ADP-753] OpenAPI: x-rate-limit

Guidelines

It SHOULD add the x-rate-limit field to endpoints with rate limits in the OpenAPI documentation.

yaml

openapi: 3.1.0
info:
  title: "Sample API"
  version: "1.0.0"
paths:
  /users:
    get:
      summary: "Fetch the user list"
      x-rate-limit:
        limit: 1000
        window: "PT1M"

SHOULD use ISO 8601 duration format for the window field
MAY include additional rate limit information such as:
- remaining: The number of requests left for the time window
- reset: The time at which the current rate limit window resets
- policy: A brief description of the rate limiting policy

Extended Example

yaml

openapi: 3.1.0
info:
  title: "Enhanced Sample API"
  version: "1.0.0"
paths:
  /users:
    get:
      summary: "Fetch the user list"
      x-rate-limit:
        limit: 1000
        window: "PT1H"
        remaining: 985
        reset: "2023-06-01T13:00:00Z"
        policy: "1000 requests per hour, per API key"

References