拡張機能リファレンス

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

拡張機能（接頭辞が x- のカスタムフィールド）を使って、OpenAPI仕様を拡張できます。これらの拡張により、追加情報を付け加えたり、異なるニーズに合わせてAPIドキュメントを調整したりできます。

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: "Manage user accounts and profiles."

x-page-icon

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

openapi.yaml

openapi: '3.0'
info: ...
tags:
  - name: "users"
    x-page-title: "Users"
    x-page-description: "Manage user accounts and profiles."
    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ブロックの「Test it」ボタンを表示または非表示にします。

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-hideTryItPanel: true

x-codeSamples

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

フィールド

フィールド名	を入力してから	説明
lang	string	コードサンプルの言語。値は次のいずれかである必要があります リスト
label	string	コードサンプルのラベル、例えば Node または Python2.7, オプション, lang はデフォルトで使用されます
source	string	コードサンプルのソースコード

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example 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: The project is live.
        PENDING: The project is pending approval.
        REJECTED: The project was rejected.

x-internal | x-gitbook-ignore

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

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-internal: true

x-stability

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

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

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      x-stability: experimental

deprecated

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

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example 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: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true
      x-deprecated-sunset: 2030-12-05