如何注释OpenAPI（Swagger）2.0中不推荐使用的字段？

Question

我有以下架构定义：

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已弃用的字段进行注释。有没有办法做到这一点？

Answer 1

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

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。

Answer 2

根据文档，使用deprecated属性就足够了

/pet/findByTags:
get:
  deprecated: true