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