# 扩展参考

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

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

前往我们的 [指南部分](https://gitbook-v2-2lie1bhe8-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/api-references/guides) 了解更多关于使用 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 代理](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/api-references/guides/using-openapi-proxy).

</details>

<details>

<summary><code>中阅读更多内容</code></summary>

x-codeSamples

#### 显示、隐藏或为 OpenAPI 块包含自定义代码示例。

<table><thead><tr><th width="103.625">字段</th><th width="88.07421875" align="center">字段名</th><th>类型</th></tr></thead><tbody><tr><td><code>描述</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>描述</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>