# 拡張機能リファレンス

拡張機能を使用して OpenAPI 仕様を強化できます。拡張機能とは、次で始まるカスタムフィールドのことです。 `x-` プレフィックス。これらの拡張機能を使うと、追加情報を付与したり、さまざまなニーズに合わせて API ドキュメントを調整したりできます。

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

こちらの [ガイドセクション](https://gitbook-v2-px7y1s8bw-gitbook.vercel.app/url/gitbook.com/docs/documentation/ja-gitbook-documentation/api-references/guides) で、OpenAPI 拡張機能を使ってドキュメントを設定する方法を詳しく確認してください。

<details>

<summary><code>x-page-title | x-displayName</code></summary>

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

{% code title="openapi.yaml" %}

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

{% endcode %}

</details>

<details>

<summary><code>x-page-description</code></summary>

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

{% code title="openapi.yaml" %}

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

{% endcode %}

</details>

<details>

<summary><code>x-page-icon</code></summary>

ページに Font Awesome アイコンを追加します。利用可能なアイコンは [こちら](https://fontawesome.com/search).

{% code title="openapi.yaml" %}

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

{% endcode %}

</details>

<details>

<summary><code>parent | x-parent</code></summary>

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

{% hint style="warning" %}
`parent` は OpenAPI 3.2+ における正式なプロパティ名です。OpenAPI 3.2 より前のバージョン（3.0.x、3.1.x）を使用している場合は、 `x-parent` を使用してください。
{% endhint %}

{% code title="openapi.yaml" %}

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

{% endcode %}

</details>

<details>

<summary><code>x-hideTryItPanel</code></summary>

OpenAPI ブロックの「テストする」ボタンを表示または非表示にします。

{% code title="openapi.yaml" %}

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

{% endcode %}

</details>

<details>

<summary><code>x-expandAllResponses</code></summary>

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

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

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">openapi: '3.0'
info: ...

# すべての操作のレスポンスを展開する
<strong>x-expandAllResponses: true
</strong>
paths:
  /pets:
    get:
      summary: ペット一覧
      responses: [...]
      # 1 つの操作だけを対象外にする
<strong>      x-expandAllResponses: false
</strong></code></pre>

</details>

<details>

<summary><code>x-expandAllModelSections</code></summary>

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

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

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">openapi: '3.0'
info: ...

# すべての操作のモデルセクションを展開する
<strong>x-expandAllModelSections: true
</strong>
paths:
  /pets:
    post:
      summary: ペットを作成する
      requestBody: [...]
      responses: [...]
      # 1 つの操作だけを対象外にする
<strong>      x-expandAllModelSections: false
</strong></code></pre>

</details>

<details>

<summary><code>x-enable-proxy</code></summary>

「テストする」リクエストを GitBook の OpenAPI プロキシ経由でルーティングします。

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

{% code title="openapi.yaml" %}

```yaml
openapi: '3.0.3'
info: ...

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

paths:
  /health:
    get:
      summary: ヘルスチェック
      # 1 つの操作だけを対象外にする
      x-enable-proxy: false
      responses:
        '200':
          description: OK
```

{% endcode %}

詳しくは [OpenAPI プロキシの使用](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/api-references/guides/using-openapi-proxy).

</details>

<details>

<summary><code>x-codeSamples</code></summary>

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

#### Fields

<table><thead><tr><th width="103.625">Field Name</th><th width="88.07421875" align="center">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>lang</code></td><td align="center">string</td><td>コードサンプルの言語。値は次のいずれかである必要があります <a href="https://github.com/github/linguist/blob/master/lib/linguist/popular.yml">list</a></td></tr><tr><td><code>label</code></td><td align="center">string</td><td>コードサンプルのラベル。たとえば <code>Node</code> または <code>Python2.7</code>, <em>optional</em>, <code>lang</code> が既定で使用されます</td></tr><tr><td><code>source</code></td><td align="center">string</td><td>コードサンプルのソースコード</td></tr></tbody></table>

{% code title="openapi.yaml" %}

```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'
```

{% endcode %}

</details>

<details>

<summary><code>x-enumDescriptions</code></summary>

スキーマ内の各 `enum` 値に個別の説明を追加します。

{% code title="openapi.yaml" %}

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

{% endcode %}

</details>

<details>

<summary><code>x-internal | x-gitbook-ignore</code></summary>

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

{% code title="openapi.yaml" %}

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

{% endcode %}

</details>

<details>

<summary><code>x-stability</code></summary>

不安定な、または進行中のエンドポイントをマークします。

対応する値: `experimental`, `alpha`, `beta`.

{% code title="openapi.yaml" %}

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

{% endcode %}

</details>

<details>

<summary><code>deprecated</code></summary>

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

{% code title="openapi.yaml" %}

```yaml
openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true
```

{% endcode %}

</details>

<details>

<summary><code>x-deprecated-sunset</code></summary>

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

対応する値: **ISO 8601** 形式（YYYY-MM-DD）

{% code title="openapi.yaml" %}

```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
```

{% endcode %}

</details>