> 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/zh/chuang-jian-nei-rong/openapi/extensions-reference.md).

# 扩展参考

GitBook 支持的 OpenAPI 扩展完整参考

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

GitBook 允许你通过可添加到 OpenAPI 规范中的多种不同扩展，调整你的 API 在已发布站点上的外观和行为。

前往我们的 [指南部分](/docs/documentation/zh/chuang-jian-nei-rong/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 区块显示或隐藏“测试”按钮。

{% 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: 成功
```

{% endcode %}

更多内容请参见 [使用 OpenAPI 代理](/docs/documentation/zh/chuang-jian-nei-rong/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">字符串</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">字符串</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">字符串</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/zh/chuang-jian-nei-rong/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.