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