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

指導方針

• 為了程式碼生成的目的，你可以(MAY)在 OpenAPI 文件中為有速率限制的端點添加 x-rate-limit 欄位。注意 - 這不是添加到回應主體中，而是添加到端點欄位！這是為了幫助程式碼生成器理解速率限制資訊。如果你沒有程式碼生成機制，你可以(MAY)在 OpenAPI 文件中省略 x-rate-limit 欄位。

TIP

如果你計劃對 API 進行速率限制，你應該始終在回應標頭中添加 RateLimit-* 標頭！

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"
      responses:
        '200':
          description: "Successful response"
          headers:
            headers:
              RateLimit-Limit:
                description: "The maximum number of requests allowed in the time window"
                schema:
                  type: integer
                  example: 1000
              RateLimit-Remaining:
                description: "The number of remaining requests in the current window"
                schema:
                  type: integer
                  example: 985
              RateLimit-Reset:
                description: "The time at which the current rate limit window resets"
                schema:
                  type: string
                  format: date-time
                  example: "2023-06-01T13:00:00Z"
        '429':
          description: "Rate limit exceeded"
          headers:
            Retry-After:
              description: "The number of seconds to wait before retrying"
              schema:
                type: integer
                example: 60
              RateLimit-Limit:
                description: "The maximum number of requests allowed in the time window"
                schema:
                  type: integer
                  example: 1000
              RateLimit-Remaining:
                description: "The number of remaining requests in the current window"
                schema:
                  type: integer
                  example: 985
              RateLimit-Reset:
                description: "The time at which the current rate limit window resets"
                schema:
                  type: string
                  format: date-time
                  example: "2023-06-01T13:00:00Z"

相關 ADPs

• ADP-138: 速率限制
• ADP-43: API 速率限制

參考資料

1. OpenAPI 規範
2. ISO 8601 持續時間格式
3. IETF 草案: HTTP 的 RateLimit 標頭屬性(property)

Changelog

• 2025-02-03: Add tips for x-rate-limit for code generation purpose and not to add to the response body.