管理 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