API 操作の管理

OpenAPI の API operation を experimental、deprecated としてマークする方法、またはドキュメントから非表示にする方法を学びます

まだ完全には安定していない、または段階的に廃止する必要がある操作は一般的です。GitBook は、これらのシナリオを管理するのに役立ついくつかの OpenAPI 拡張をサポートしています。

操作を experimental、alpha、または beta としてマークする

使用 x-stability エンドポイントが不安定である、または進行中であることを伝えるためです。これにより、ユーザーは本番対応前のエンドポイントを避けやすくなります。サポートされる値: experimental, alpha, beta.

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      x-stability: experimental

操作を非推奨にする

操作を非推奨としてマークするには、 deprecated: true 属性を追加します。

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      deprecated: true

必要に応じて、サポート終了時期を指定するには、 x-deprecated-sunset

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      deprecated: true
      x-deprecated-sunset: 2030-12-05

API リファレンスから操作を非表示にする

API リファレンスから操作を非表示にするには、 x-internal: true または x-gitbook-ignore: true 属性を追加します。

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      x-internal: true

レスポンスサンプルを非表示にする

を追加します x-hideSample: true 属性をレスポンスオブジェクトに追加して、レスポンスサンプルセクションから除外します。

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      responses:
        200:
          x-hideSample: true

認証プレフィックスとトークンのプレースホルダーをカスタマイズする

認証プレフィックス（たとえば、 Bearer, Token、または任意のカスタム文字列）と、GitBook でセキュリティスキームを使用するときに表示されるトークンのプレースホルダーをカスタマイズできます。

OpenAPI 仕様の components.securitySchemesの下で、次のようにスキームを定義します:

openapi.yaml

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      x-gitbook-prefix: Token
      x-gitbook-token-placeholder: YOUR_CUSTOM_TOKEN

これらの拡張は:

• x-gitbook-prefix トークンの前に追加されるプレフィックスを定義します。

  • 例: Authorization: <x-gitbook-prefix> YOUR_API_TOKEN

• x-gitbook-token-placeholder デフォルトのトークン値を設定します。

  • 例: Authorization: Bearer <x-gitbook-token-placeholder>

x-gitbook-prefix には対応していません http セキュリティスキームは、標準の IANA 認証定義に従う必要があるためです。 詳細を見る