如何在 OpenAPI 中弃用整个 API？

Question

我想找到一种方法将 API 标记为已弃用。

这是一种可能的情况：开发了 GraphQL API，而不是 REST API，但为了顺利停用旧的 REST API，我想首先将其标记为已弃用。我想用最少的编辑量来完成此操作（不将每个操作标记为已弃用）。

Answer 1

deprecated

仅在 operation、

parameter

或

schema

属性官方

支持

您始终可以在 OpenAPI 文件的根目录中使用自定义

x-deprecated

。不确定许多工具是否支持它。否则，应在每个操作中定义已弃用的内容。

这里有一个示例以及针对您的服务推荐的弃用策略。

当您标记 api

deprecated

时，请通过标头告知您的消费者。继续返回 200 并向他们提供弃用日期、服务的日落日期以及替代品的链接（如果存在）。

弃用日期过后，在服务上返回 410，直到日落日期到来，并提供替换链接。

openapi: 3.0.4
info:
  title: a sample api deprecation
  version: 1.0.0
x-deprecated: true
paths:
  '/thing':
    get:
      summary: my old api
      deprecated: true
      responses:
        '200':
          description: OK
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
            Link:
              $ref: '#/components/headers/Link'
          content:
            'application/json':
              schema: {}
        '410':
          description: Gone
          headers:
            Sunset:
              $ref: '#/components/headers/Sunset'
            Link:
              $ref: '#/components/headers/Link'
          content:
            'application/json':
              schema: {}
components:
  headers:
    Deprecation:
      description: Contains the version and/or datetime of a deprecated resource
        related to the request URI.
      required: false
      schema:
        type: string
      examples:
        deprecation:
          value: '"deprecation": "version =v1; date = "2024-04-30T00:00:00Z"'
    Sunset:
      description: 'Contains the retirement datetime of a resource related to the
        request URI. Note: For historical reasons the datetime format differs from
        the Deprecation datetime format.[Dalal et al. (2023)]'
      required: false
      schema:
        type: string
      examples:
        sunset:
          value: '"sunset": "Fri 8 Mar 2024 23:59:00 GMT"'
    Link:
      description: Expresses a typed relationship with another resource
      required: false
      schema:
        type: string
        format: uri