29

自動生成ではなく、手作業で API ドキュメントを準備しています。すべての API に送信する必要があるヘッダーがあり、API 全体に対してグローバルにパラメーターを定義できるかどうかわかりません。

これらのヘッダーの一部は静的で、一部は API の呼び出し時に設定する必要がありますが、すべての API で同じです。各 API と各メソッドのパラメーターをコピーして貼り付けたくありません。将来的に保守可能。

API 定義による静的ヘッダーを見ましたが、誰かがそれらを設定または使用する方法についての単一のドキュメントはありません。

これはまったく可能ですか？

4

4 に答える 4

23

API を呼び出すときにコンシューマから送信されるヘッダー パラメータについて話している場合は...

パラメータ セクションで少なくとも 1 回定義し、必要な場合にのみ参照することができます。以下の例では:

  • CommonPathParameterHeader、ReusableParameterHeaderおよびドキュメントのルートでAnotherReusableParameterHeader一度だけ定義さparametersれ、任意のパラメーターリストで使用できます
  • CommonPathParameterHeaderおよびパスparametersのセクションで参照されます。つまり、これらのパスのすべての操作にはこのヘッダーが必要です/resources/other-resources
  • ReusableParameterHeaderget /resourcesこの操作で必要であるという意味で参照されます
  • AnotherReusableParameterHeaderで同じことget /other-resources

例：

swagger: '2.0'
info:
  version: 1.0.0
  title: Header API
  description: A simple API to learn how you can define headers

parameters:
  CommonPathParameterHeader:
    name: COMMON-PARAMETER-HEADER
    type: string
    in: header
    required: true
  ReusableParameterHeader:
    name: REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true
  AnotherReusableParameterHeader:
    name: ANOTHER-REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true

paths:
  /resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/ReusableParameterHeader'
      responses:
        '200':
          description: gets some resources
  /other-resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/AnotherReusableParameterHeader'
      responses:
        '200':
          description: gets some other resources
    post:
      responses:
        '204':
          description: Succesfully created.

各 API 応答で送信されるヘッダーについて話している場合...

残念ながら、再利用可能な応答ヘッダーを定義することはできません。ただし、少なくとも、500 エラーなどの一般的な HTTP 応答に対して、これらのヘッダーを含む再利用可能な応答を定義できます。

例：

swagger: '2.0'
info:
  version: 1.0.0
  title: Header API
  description: A simple API to learn how you can define headers

parameters:
  CommonPathParameterHeader:
    name: COMMON-PARAMETER-HEADER
    type: string
    in: header
    required: true
  ReusableParameterHeader:
    name: REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true
  AnotherReusableParameterHeader:
    name: ANOTHER-REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true

paths:
  /resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/ReusableParameterHeader'
      responses:
        '200':
          description: gets some resources
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
  /other-resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/AnotherReusableParameterHeader'
      responses:
        '200':
          description: gets some other resources
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
    post:
      responses:
        '204':
          description: Succesfully created.
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
        '500':
          $ref: '#/responses/Standard500ErrorResponse'

responses:
  Standard500ErrorResponse:
    description: An unexpected error occured.
    headers:
      X-Rate-Limit-Remaining:
        type: integer
      X-Rate-Limit-Reset:
        type: string
        format: date-time

OpenAPI (fka.Swagger) について 次のバージョン

OpenAPI 仕様 (fka.Swagger) は進化し、特に再利用可能な応答ヘッダーの定義が含まれます ( https://github.com/OAI/OpenAPI-Specification/issues/563を参照)。

于 2016-05-16T12:50:02.600 に答える
4

この Swagger issue commentによると、グローバル パラメーター (ヘッダー パラメーターを含む) のサポートは近い将来には予定されていませんが、繰り返しを制限するには、@Arnaud の回答 ( parameters: - $ref: '#/parameters/paramX') のようにパラメーター参照を使用する必要があります。

于 2015-12-07T12:35:14.547 に答える