# 扩展参考

您可以使用扩展来增强您的 OpenAPI 规范——以 `x-` 为前缀的自定义字段。这些扩展可让您添加额外信息，并根据不同需求定制您的 API 文档。

GitBook 允许您通过一系列可添加到 OpenAPI 规范中的不同扩展，来调整您的 API 在已发布站点上的外观和工作方式。

前往我们的 [指南部分](/docs/documentation/zh/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+ 中的官方属性名称。如果使用 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 块的“测试一下”按钮。

{% 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>

默认展开所有响应部分，而不是一次只显示一个。

将其添加到根级别以应用于每个操作。将其添加到某个操作上以仅应用于该端点。

<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 代理转发“测试一下”请求。

将其添加到根级别以应用于每个操作。将其添加到某个操作上以仅应用于该端点。操作会覆盖根值。

{% 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/zh/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: 示例摘要
      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>

为 schema 中每个 `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: 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/zh/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.