How to annotate a field as deprecated in OpenAPI (Swagger) 2.0?

Question

I have the following schema definition:

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'

I would like to do annotate the location field as deprecated. Is there a way to do this?

score 110 · Answer 1 · answered Apr 17 '18 at 08:13

The possibility to mark schemas and schema properties as deprecated was added in 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    # <---------

If you use OpenAPI 2.0 (Swagger 2.0), the only thing you can do is document the deprecation verbally in the property description.

score 28 · Answer 2 · edited Mar 06 '23 at 23:06

28

According to the documentation it is enough to use the deprecated attribute:

paths:
  /pet/findByTags:
    get:
      deprecated: true

edited Mar 06 '23 at 23:06

Helen

87,344
17
243
314

answered Nov 28 '18 at 19:56

Tomas

1,531
1
16
22

10

He asked for "ttribute", not the endpoint. @Helen has a correct anwer: not possible in OpenAPI 2.0 – Samoht Jan 18 '19 at 11:03
1

@Samoht while you're correct that this doesn't answer the question, Google will show this as the top result for "swagger service deprecated" – tharkay Aug 16 '21 at 12:13

How to annotate a field as deprecated in OpenAPI (Swagger) 2.0?

2 Answers2