如何在OpenAPI (Swagger) 2.0中标记字段为弃用？

因为Swagger 2.0本身并没有为字段提供官方的deprecated属性（这个特性是在OpenAPI 3.0+才正式引入的），不过我们有几种通用且被广泛认可的方式来实现这个需求：

• 在字段的description中明确标注弃用信息
  这是最直接易懂的方式，开发者查看文档时一眼就能捕捉到弃用提示。你可以更新location字段的描述，加上醒目的弃用标识、弃用原因或替代方案（如果有的话）：

  definitions:
    Service:
      type: object
      properties:
        serviceId:
          type: string
          description: 设备或服务识别码
          example: 1111111111
        location:
          type: string
          description: 【已弃用】服务所在位置，请使用`structuredAddress`字段替代（示例替代字段）
          example: '400 Street name, City State postcode, Country'
  

• 使用Swagger自定义扩展字段x-deprecated
  Swagger支持以x-开头的自定义扩展字段，很多主流的Swagger工具（比如Swagger UI、代码生成器）都能识别并展示这个标记。你可以直接给location字段添加该扩展：

  definitions:
    Service:
      type: object
      properties:
        serviceId:
          type: string
          description: 设备或服务识别码
          example: 1111111111
        location:
          type: string
          description: 服务所在位置
          example: '400 Street name, City State postcode, Country'
          x-deprecated: true
  

  还可以搭配额外的扩展字段补充更多细节：

  x-deprecated: true
  x-deprecated-reason: "该字段将被结构化的`address`字段替代，包含更规范的地址层级信息"
  

• 结合两种方式（推荐）
  为了兼顾人工阅读和工具解析的体验，建议同时使用描述标注和扩展字段：既在description里用醒目的文字提示开发者，又添加x-deprecated让工具识别并做相应处理（比如在UI中灰化字段、代码生成时给出警告）。

如果之后有计划迁移到OpenAPI 3.0+版本，直接使用官方标准的deprecated: true属性即可，这是最规范的做法。

内容的提问来源于stack exchange，提问作者saeedj