「テストする」ボタンの設定

GitBook では、いくつかの OpenAPI 拡張を使って「Test It」ボタンとそれに付随するウィンドウを設定できます。これらの拡張は、ユーザー向けのテストスイートの改善と設定に役立ちます。

「Test it」ボタンを非表示にする

エンドポイントに x-hideTryItPanel を追加することで、または OpenAPI 仕様のルートで「Test it」ボタンを非表示にできます。

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: 例の概要
      description: 例の説明
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-hideTryItPanel: true

「Test it」リクエストをプロキシする

一部の API ではブラウザからのリクエストがブロックされます。多くの場合、その理由は CORS です。

ルート テストする GitBook 経由でトラフィックを中継するには、 x-enable-proxy を仕様に追加してください。

以下を参照 OpenAPI プロキシの使用して例を確認してください。

テストウィンドウで認証を有効にする

リクエストランナーが認証を表示して適用できるのは、仕様でそれが宣言されている場合のみです。スキームを components.securitySchemesの下に定義し、次に security を使ってグローバルに、または操作ごとに（グローバル設定を上書き）関連付けます。

認証スキームを宣言する

以下は一般的なパターンです。YAML では通常の引用符を使用してください。

openapi: '3.0.3'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

openapi: '3.0.3'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

openapi: '3.0.3'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://auth.example.com/oauth/authorize'
          tokenUrl: 'https://auth.example.com/oauth/token'
          scopes:
            read:items: 'アイテムを読む'
            write:items: 'アイテムを書き込む'

スキームをグローバルまたは操作ごとに適用する

openapi: '3.0.3'
security:
  - bearerAuth: []
paths: ...

paths:
  /reports:
    get:
      summary: レポートを取得
      security:
        - apiKeyAuth: []
      responses:
        '200':
          description: OK

でエンドポイントURLを制御する `servers`

リクエストランナーは、あなたが servers 配列で定義した URL を対象にします。1 つ以上のサーバーを宣言できます。変数を使ってパラメータ化することもできます。

openapi: '3.0.3'
servers:
  - url: https://instance.api.region.example.cloud

servers:
  - url: https://api.example.com
    description: 本番
  - url: https://staging-api.example.com
    description: ステージング

servers:
  - url: https://{instance}.api.{region}.example.cloud
    variables:
      instance:
        default: acme
        description: あなたのテナントまたはインスタンスのスラッグ
      region:
        default: eu
        enum:
          - eu
          - us
          - ap
        description: 地域ごとのデプロイ

paths:
  /reports:
    get:
      summary: レポートを取得
      servers:
        - url: https://reports.api.example.com
      responses:
        '200':
          description: OK

最終更新 2 か月前

役に立ちましたか？