Swagger response validator

Input
Output

Swagger Response Validator

Older APIs are often still described in Swagger 2.0. Paste a response and the swagger.json (or YAML), and check the body against the operation's response schema, with #/definitions references, x-nullable and enums read the way Swagger means them.

Example: pets from a Swagger 2.0 API

GET /pet/findByStatus returns a list of Pet, from #/definitions. The first pet has no name, which the spec requires, and the second has a status the enum doesn't allow:

The response

[
  {
    "id": 12,
    "status": "available",
    "tags": [
      {
        "id": 1,
        "name": "dog"
      }
    ]
  },
  {
    "id": 13,
    "name": "Mochi",
    "status": "adopted",
    "category": {
      "id": 2,
      "name": "Cats"
    }
  }
]

swagger.json

{
  "swagger": "2.0",
  "info": {
    "title": "Pet store",
    "version": "1.0"
  },
  "basePath": "/v2",
  "paths": {
    "/pet/findByStatus": {
      "get": {
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "ok",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Pet"
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Pet": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "available",
            "pending",
            "sold"
          ]
        },
        "category": {
          "$ref": "#/definitions/Category"
        },
        "tags": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Tag"
          }
        }
      }
    },
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        }
      }
    }
  }
}

Output

GET /pet/findByStatus → 200: 2 problems
✕ $[0]: Missing required key "name"
✕ $[1].status: Must be one of "available", "pending", "sold"

How do I use the Swagger response validator?

  1. Paste the JSON response.
  2. Paste the Swagger 2.0 document (or an OpenAPI 3 one) in the second box.
  3. Name the operation, like GET /pet/findByStatus, and read the list of problems.

What does the Swagger response validator do?

  • Swagger 2.0 and OpenAPI 3.0 and 3.1
  • #/definitions and #/components references
  • A report you can copy into a bug ticket

When to use the Swagger response validator

Plenty of APIs, internal ones especially, are still described by a Swagger 2.0 file that nobody has looked at in a while. Checking a real response against it shows quickly whether the file still tells the truth, before you generate a client from it or hand it to another team.

In Swagger 2.0 the response schema sits directly under responses, references point to #/definitions, and x-nullable: true marks a field that can be null. Bracely reads all of those, and OpenAPI 3.0 and 3.1 documents in the same box, as JSON or YAML. The operation can be named with or without the basePath: GET /pet/findByStatus and https://petstore.example.com/v2/pet/findByStatus find the same one.

Frequently asked questions

Should I convert my Swagger 2.0 file to OpenAPI 3?
Not to check responses: both work here. Convert when your tools need 3.x, for example for oneOf, nullable without an extension, or several content types per response.
What does "Not in the spec" mean?
The response has a field the schema doesn't list. Swagger allows extra fields unless the schema says otherwise, so it isn't counted as a problem, but it's worth adding to the spec.
Is my data uploaded?
No. Bracely runs entirely in your browser, so nothing you paste or open leaves your device.

More JSON tools

Bracely has 104 JSON tools in one page. Related ones:

Runs entirely in your browser. Nothing you paste is uploaded. Made by Saurabh Pagrut · About · Privacy policy
Last updated · Version 6.1 · Changelog
Saurabh Pagrut on GitHub · LinkedIn · X · YouTube · Instagram