openapi - Swagger / Open API 2.0 共通の応答ヘッダーを宣言できますか?

Question

各応答構造にコピーせずに、すべての応答に存在するカスタム応答ヘッダーを宣言することは可能ですか?

Answer 1

これは OpenAPI 3.0 でいくらか改善されました。インライン定義を繰り返す代わりに、グローバルcomponents/headersセクションで共通ヘッダーを定義してから、これらの定義を定義できるようになりました。コードの重複を少し減らすために、応答全体 (400 など) を使用する$refこともできます。$refただし、すべてのパスに共通のヘッダーを設定する方法はまだありません。各応答でヘッダーを明示的にリストする必要があります。

openapi: 3.0.1
...
paths:
  /:
    get:
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
  /something:
    get:
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'

components:
  headers:
    X-RateLimit-Limit:
      description: Request limit per hour
      schema:
        type: integer
      example: 100
    X-RateLimit-Remaining:
      schema:
        type: integer
      example: 96

Answer 2

Writing OpenAPI (Swagger) Specification Tutorial – Part 5 – Advanced Input And Output Modelingのセクション 2.3 Response's headers によると、答えはノーです。これは、2.0仕様からも理解できます。

構造の改善に関する投票/コメント: ヘッダー処理の強化 · Issue #690 · OAI/OpenAPI-Specification .