管理 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 身份验证定义。 了解更多