API 操作の管理

OpenAPI の API 操作を実験的、非推奨としてマークしたり、ドキュメントから非表示にする方法を学ぶ

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

操作を実験的、アルファ、またはベータとしてマークする

次を使用します： 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 認証定義に従う必要があるためです。 詳細を学ぶ