Swagger: How to get formatted example json

Question

I'm really struggling to understand the format of the examples section of a response. I have the following response defined for a 500 Internal Sever error.

500InternalServerError:
    description: The server encountered an unexpected condition which prevented it from fulfilling the request
    schema:
      allOf:
        - $ref: '#/definitions/Failure'
    headers:
      X-Rate-Limit-Limit:
        description: The number of allowed requests in the current period
        type: integer
      X-Rate-Limit-Remaining:
        description: The number of remaining requests in the current period
        type: integer
      X-Rate-Limit-Reset:
        description: The number of seconds left in the current period
        type: integer
    examples:
      application/json:
        code: -1
        message: The server encountered an unexpected condition which prevented it from fulfilling the request

When I load it up in swagger-ui, it looks like this:

How do I get the response to be formatted over multiple lines and look like this?:

{
  "code": "-1",
  "message": "The server encountered an unexpected condition which prevented it from fulfilling the request"
}

score 1 · Answer 1 · answered Apr 18 '17 at 20:32

The lack of pretty print in the response-level examples seems to be a bug or missing functionality in Swagger UI 3.0.x. Feel free to submit an issue on GitHub.

The workaround is to use a schema-level example instead:

definitions:
  Failure:
    type: object
    ...
    example:
      code: "-1"  # Quotes force the number to be treated as a string
      message: The server encountered an unexpected condition which prevented it from fulfilling the request

By the way, you do not need allOf when using $ref alone (without combining it with other items):

schema:
  $ref: '#/definitions/Failure'

Swagger: How to get formatted example json

1 Answers1