API Documentation. Multiple examples in Swagger

When describing the API documentation, sometimes there is a need to add several examples of responses. This is necessary for the possibility of a more complete description of the API documentation, since this API documentation is a kind of contract between the backend and the frontend. If you still use Swagger v.2.0 then you face the limitation - adding multiple examples is not supported. To get around this limitation, you need to go to the OpenAPI v. 3.0.0 specification. Then you will be able to add examples as follows.

- One example:

responses:
  "200":
    description: user creation successful
    content:
      application/json:
        example:
          token: fEt4IouUyRrqlx80treEWwq8
- A few examples:

responses:
  "422":
    description: user creation failed
    content:
      application/json:
        schema:
          properties:
            response:
              $ref: "#/components/schemas/ErrorResponse"
        examples:
          "Missing parameters":
            value:
              error: 'error-1'
              message: 'error-message-1'
          "Validation failed":
            value:
              error: 'error-2'
              message: 'error-message-2'


The differences between Swagger v.2.0 and the OpenAPI v. 3.0.0 specification are generally not so big:

    Swagger v.2.0     |  OpenAPI v.3.0.0
----------------------|-------------------
    info              |    info
----------------------|-------------------
   host               |
   basePath           |    servers
   schemes            |
----------------------|-------------------
   security           |    security
----------------------|-------------------
   paths              |   paths
----------------------|-------------------
   externalDocs       |   externalDocs
----------------------|-------------------
   tags               |   tags
----------------------|-------------------
                      |
  securityDefinitions |
                      |  components:
----------------------|    parameters
   produces           |    responses
----------------------|    examples
   consumes           |    requestBodies
----------------------|    headers
   definitions        |    links
   parameters         |    callbacks
   responses          |    securitySchemes
                      |

So the transition itself should not be difficult.

No comments :

Post a Comment