扩展参考

GitBook 支持的 OpenAPI 扩展完整参考

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

GitBook 允许您通过向 OpenAPI 规格添加各种扩展，调整已发布站点上 API 的外观和行为。

前往我们的 指南部分 了解有关使用 OpenAPI 扩展配置文档的更多信息。

x-page-title | x-displayName

更改导航和页面标题中使用的标签显示名称。

openapi.yaml

openapi: '3.0'
info: ...
tags:
  - name: users
    x-page-title: Users

x-page-description

为页面添加描述。

openapi.yaml

openapi: '3.0'
info: ...
tags:
  - name: "users"
    x-page-title: "Users"
    x-page-description: "Manage user accounts and profiles."

x-page-icon

为页面添加 Font Awesome 图标。查看可用图标 这里.

openapi.yaml

openapi: '3.0'
info: ...
tags:
  - name: "users"
    x-page-title: "Users"
    x-page-description: "Manage user accounts and profiles."
    x-page-icon: "user"

x-parent | parent

为标签添加层级，以便在 GitBook 中组织页面。

openapi.yaml

openapi: '3.0'
info: ...
tags:
  - name: organization
  - name: admin
    x-parent: organization
  - name: user
    x-parent: organization

x-hideTryItPanel

显示或隐藏 OpenAPI 模块的“测试它”按钮。

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-hideTryItPanel: true

x-codeSamples

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

字段

字段名称	输入	描述
lang	string	代码示例语言。值应为以下之一 列表
label	string	代码示例标签，例如 Node 或 Python2.7, 可选, lang 被默认使用
source	string	代码示例源代码

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-codeSamples:
        - lang: 'cURL'
          label: 'CLI'
          source: |
            curl -L \
            -H 'Authorization: Bearer <token>' \
            'https://api.gitbook.com/v1/user'

x-enumDescriptions

为模式中的每个 enum 值添加单独的描述。

openapi.yaml

openapi: '3.0'
info: ...
components:
  schemas:
    project_status:
      type: string
      enum:
        - LIVE
        - PENDING
        - REJECTED
      x-enumDescriptions:
        LIVE: The project is live.
        PENDING: The project is pending approval.
        REJECTED: The project was rejected.

x-internal | x-gitbook-ignore

将端点从您的 API 参考中隐藏。

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-internal: true

x-stability

标记不稳定或正在进行中的端点。

支持的值： experimental, alpha, beta.

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      x-stability: experimental

deprecated

标记端点是否已弃用。已弃用的端点将在您发布的站点中显示弃用警告。

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true

x-deprecated-sunset

为已弃用的操作添加淘汰日期。

支持的值： ISO 8601 格式 (YYYY-MM-DD)

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true
      x-deprecated-sunset: 2030-12-05