如何注释 OpenAPI (Swagger) 2.0 中已弃用的字段？

Posted 2023-02-16

【中文标题】如何注释 OpenAPI (Swagger) 2.0 中已弃用的字段？

【英文标题】：How to annotate a field as deprecated in OpenAPI (Swagger) 2.0?

【发布时间】：2018-09-26 22:46:04

【问题描述】：

我有以下架构定义：

swagger: '2.0'
...
definitions:
  Service:
    type: object
    properties:
      serviceId:
        type: string
        description: Device or service identification number
        example: 1111111111      
      location:
        type: string
        description: Location of the service
        example: '400 Street name, City State postcode, Country'

我想将location 字段注释为已弃用。有没有办法做到这一点？

【参考方案1】：

在 OpenAPI 3.0 中添加了将架构和架构属性标记为 deprecated 的可能性：

openapi: 3.0.1
...
components:
  schemas:
    Service:
      type: object
      properties:
        location:
          type: string
          description: Location of the service
          example: '400 Street name, City State postcode, Country'
          deprecated: true    # <---------

如果您使用 OpenAPI 2.0 (Swagger 2.0)，您唯一能做的就是在属性 description 中口头记录弃用。

【参考方案2】：

根据documentation使用deprecated属性就够了

/pet/findByTags:
get:
  deprecated: true

【讨论】：

他要求的是“属性”，而不是终点。 @Helen 有一个正确的答案：在 OpenAPI 2.0 中不可能

@Samoht 虽然你是对的，这并没有回答问题，但 Google 会将其显示为“不推荐使用 swagger 服务”的最高结果