API オペレーションの管理

OpenAPI の API オペレーションを実験的、非推奨としてマークしたり、ドキュメントから非表示にする方法を学びましょう

まだ完全に安定していない、または段階的に廃止する必要があるオペレーションはよくあります。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 認証定義に従う必要があるためです。 詳細を見る