拡張機能リファレンス

GitBook がサポートする OpenAPI 拡張機能の完全なリファレンス

拡張機能を使って OpenAPI 仕様を強化できます— x- x- プレフィックスで始まるカスタムフィールドです。

GitBook を使うと、OpenAPI スペックに追加できるさまざまな拡張機能を通じて、公開サイト上で API の見た目や動作を調整できます。

詳しくは ガイドセクション をご覧ください。OpenAPI 拡張機能を使ってドキュメントを設定する方法の詳細を確認できます。

x-page-title | x-displayName

ナビゲーションとページタイトルで使われるタグの表示名を変更します。

openapi.yaml

openapi: '3.0'
info: ...
tags:
  - name: users
    x-page-title: Users

x-page-description

ページに説明を追加します。

openapi.yaml

openapi: '3.0'
info: ...
tags:
  - name: "users"
    x-page-title: "Users"
    x-page-description: "ユーザーアカウントとプロフィールを管理します。"

x-page-icon

ページに Font Awesome アイコンを追加します。利用可能なアイコンを参照してください こちら.

openapi.yaml

openapi: '3.0'
info: ...
tags:
  - name: "users"
    x-page-title: "Users"
    x-page-description: "ユーザーアカウントとプロフィールを管理します。"
    x-page-icon: "user"

parent | x-parent

GitBook でページを整理するために、タグに階層構造を追加します。

parent は OpenAPI 3.2+ における正式なプロパティ名です。OpenAPI 3.2 より前のバージョン（3.0.x、3.1.x）を使う場合は、 x-parent 代わりにこちらを使用してください。

openapi.yaml

openapi: '3.2'
info: ...
tags:
  - name: organization
  - name: admin
    parent: organization
  - name: user
    parent: organization    

x-hideTryItPanel

OpenAPI ブロックで「試す」ボタンを表示または非表示にします。

openapi.yaml

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

x-expandAllResponses

1つずつではなく、すべてのレスポンスセクションを既定で展開します。

ルートに追加するとすべての操作に適用されます。操作に追加すると、そのエンドポイントにのみ適用されます。

openapi.yaml

openapi: '3.0'
info: ...

# すべての操作でレスポンスをすべて展開
x-expandAllResponses: true

paths:
  /pets:
    get:
      summary: ペット一覧
      responses: [...]
      # 単一の操作では無効化
      x-expandAllResponses: false

x-expandAllModelSections

ネストされたオブジェクトのプロパティをユーザー操作なしで表示し、すべてのモデル/スキーマセクションを既定で展開します。

ルートに追加するとすべての操作に適用されます。操作に追加すると、そのエンドポイントにのみ適用されます。

openapi.yaml

openapi: '3.0'
info: ...

# すべての操作でモデルセクションをすべて展開
x-expandAllModelSections: true

paths:
  /pets:
    post:
      summary: ペットを作成
      requestBody: [...]
      responses: [...]
      # 単一の操作では無効化
      x-expandAllModelSections: false

x-enable-proxy

GitBook の OpenAPI プロキシ経由で「試す」リクエストを送信します。

ルートに追加するとすべての操作に適用されます。操作に追加すると、そのエンドポイントにのみ適用されます。操作はルートの値より優先されます。

openapi.yaml

openapi: '3.0.3'
info: ...

# すべての操作でプロキシを有効化
x-enable-proxy: true

paths:
  /health:
    get:
      summary: ヘルスチェック
      # 単一の操作では無効化
      x-enable-proxy: false
      responses:
        '200':
          description: OK

詳細はこちら OpenAPI プロキシの使用.

x-codeSamples

OpenAPI ブロックのカスタムコードサンプルを表示、非表示、または追加します。

フィールド

フィールド名	種類	説明
lang	string	コードサンプルの言語。値は次のいずれかである必要があります list
label	string	コードサンプルのラベル。たとえば Node または Python2.7, optional, lang が既定で使用されます
source	string	コードサンプルのソースコード

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: 例の概要
      description: 例の説明
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-codeSamples:
        - lang: 'cURL'
          label: 'CLI'
          source: |
            curl -L \\
            -H 'Authorization: Bearer <token>' \\
            'https://api.gitbook.com/v1/user'

x-enumDescriptions

各 enum 値ごとに個別の説明を追加します。

openapi.yaml

openapi: '3.0'
info: ...
components:
  schemas:
    project_status:
      type: string
      enum:
        - LIVE
        - PENDING
        - REJECTED
      x-enumDescriptions:
        LIVE: プロジェクトは公開中です。
        PENDING: プロジェクトは承認待ちです。
        REJECTED: プロジェクトは却下されました。

x-internal | x-gitbook-ignore

API リファレンスからエンドポイントを非表示にします。

openapi.yaml

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

x-stability

不安定または進行中のエンドポイントにマークを付けます。

サポートされる値: experimental, alpha, beta.

openapi.yaml

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

deprecated

エンドポイントが非推奨かどうかを示します。非推奨のエンドポイントには、公開サイトで非推奨警告が表示されます。

openapi.yaml

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

x-deprecated-sunset

非推奨の操作にサンセット日を追加します。

サポートされる値: ISO 8601 形式（YYYY-MM-DD）

openapi.yaml

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