# 拡張機能リファレンス

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

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

こちらの [ガイドセクション](/docs/documentation/ja-gitbook-documentation/api-references/guides.md) で、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 ブロックの「Test it」ボタンを表示または非表示にします。

{% 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: [...]
      # 単一の操作では無効にする
<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: [...]
      # 単一の操作では無効にする
<strong>      x-expandAllModelSections: false
</strong></code></pre>

</details>

<details>

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

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

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

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

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

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

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

{% endcode %}

詳しくは [OpenAPI プロキシの使用](/docs/documentation/ja-gitbook-documentation/api-references/guides/using-openapi-proxy.md).

</details>

<details>

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

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

**フィールド**

<table><thead><tr><th width="103.625">フィールド名</th><th width="88.07421875" align="center">入力します</th><th>説明</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">一覧</a></td></tr><tr><td><code>ラベル</code></td><td align="center">string</td><td>コードサンプルのラベル。例： <code>Node</code> または <code>Python2.7</code>, <em>任意</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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/api-references/extensions-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.