> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/openapi/extensions-reference.md).

# 拡張機能リファレンス

OpenAPI 仕様を拡張機能で強化できます— `x-` 接頭辞。これらの拡張機能を使うと、追加情報を加えたり、さまざまなニーズに合わせて API ドキュメントを調整したりできます。

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

こちらの [ガイドセクション](/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/openapi/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: ユーザー
```

{% 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: "ユーザー"
    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: "ユーザー"
    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+ における正式なプロパティ名です。3.2 より前の OpenAPI バージョン (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: 例の要約
      description: 例の説明
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-hideTryItPanel: true
```

{% endcode %}

</details>

<details>

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

各応答セクションを 1 つずつではなく、既定ですべて展開します。

ルートに追加すると、すべてのオペレーションに適用されます。オペレーションに追加すると、その 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>

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

ルートに追加すると、すべてのオペレーションに適用されます。オペレーションに追加すると、その 1 つのエンドポイントに適用されます。

<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 プロキシ経由で「Test it」リクエストをルーティングします。

ルートに追加すると、すべてのオペレーションに適用されます。オペレーションに追加すると、その 1 つのエンドポイントに適用されます。オペレーションはルート値を上書きします。

{% 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 プロキシの使用](/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/openapi/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>label</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: 例の要約
      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: 例の要約
      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: 例の要約
      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: 例の要約
      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: 例の要約
      description: 例の説明
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true
      x-deprecated-sunset: 2030-12-05
```

{% endcode %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/openapi/extensions-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.