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 認証定義に従う必要があるためです。 詳細を見る