管理 API 操作

了解如何将 OpenAPI API 操作标记为实验性、已弃用，或将其从文档中隐藏

这种情况很常见：有些操作还不够稳定，或者需要逐步下线。GitBook 支持若干 OpenAPI 扩展，帮助你管理这些场景。

将操作标记为实验版、alpha 或 beta

使用 x-stability 用于说明某个端点不稳定或仍在开发中。这有助于用户避免使用尚未适合生产环境的端点。支持的值： experimental, alpha, beta.

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      x-stability: experimental

将操作标记为已弃用

要将某个操作标记为已弃用，请添加 deprecated: true 属性。

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      deprecated: true

你也可以通过包含以下内容来指定支持结束时间： x-deprecated-sunset

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      deprecated: true
      x-deprecated-sunset: 2030-12-05

从 API 参考中隐藏某个操作

要从你的 API 参考中隐藏某个操作，请添加 x-internal: true 或者 x-gitbook-ignore: true 属性。

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      x-internal: true

隐藏响应示例

添加 x-hideSample: true 属性到响应对象，以将其从响应示例部分中排除。

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      responses:
        200:
          x-hideSample: true

自定义授权前缀和令牌占位符

你可以自定义授权前缀（例如， Bearer, Token，或自定义字符串）以及在 GitBook 中使用安全方案时显示的令牌占位符。

在你的 OpenAPI 规范中，在 components.securitySchemes下，像这样定义你的方案：

openapi.yaml

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      x-gitbook-prefix: Token
      x-gitbook-token-placeholder: YOUR_CUSTOM_TOKEN

这些扩展：

• x-gitbook-prefix 定义添加到令牌前面的前缀。

  • 示例： Authorization: <x-gitbook-prefix> YOUR_API_TOKEN

• x-gitbook-token-placeholder 设置默认令牌值。

  • 示例： Authorization: Bearer <x-gitbook-token-placeholder>

x-gitbook-prefix 不受支持，适用于 http 安全方案，因为这些方案必须遵循标准的 IANA 身份验证定义。 了解更多