> 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).

# 扩展参考

你可以使用扩展来增强你的 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: ...
标签：
  - name: users
    x-page-title: 用户
```

{% endcode %}

</details>

<details>

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

为页面添加说明。

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

```yaml
openapi: '3.0'
info: ...
标签：
  - 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: ...
标签：
  - 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: ...
标签：
  - 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>

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

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

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

{% 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">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>可选</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/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.