Swagger Validator Badge
This project shows a "valid swagger" badge on your site, supporting Swagger/OpenAPI 2.0 and OpenAPI 3.x specifications.
There is an online version hosted on http://validator.swagger.io.
You can also pull a docker image of the validator directly from DockerHub, e.g.:
docker pull swaggerapi/swagger-validator-v2:v2.1.0
docker run -it -p 8080:8080 --name swagger-validator-v2 swaggerapi/swagger-validator-v2:v2.1.0
Since version 2.0.2
local and non http/https urls are rejected by default, along with redirects; this is controllable with docker env variables / java system properties:
docker run -it -p 8080:8080 -e "REJECT_LOCAL=false" -e "REJECT_REDIRECT=false" --name swagger-validator-v2 swaggerapi/swagger-validator-v2:v2.1.0
In non docker environments, system properties rejectLocal
and rejectRedirect
can be used.
Web UI is reachable at http://localhost:8080/index.html and OpenAPI spec at http://localhost:8080/validator/openapi.json
You can validate OpenAPI specifications version 2.0 (Swagger), 3.0 and 3.1. Swagger Parser is used for semantic validation.
Depending on jsonSchemaValidation
query parameter value also JSON Schema validation can be executed (default to true
)
Additional parameters allow to customize parsing and validation mode.
<img src="https://validator.swagger.io/validator?url={YOUR_URL}">
Of course the YOUR_URL
needs to be addressable by the validator (i.e. won't find anything on localhost). If it validates, you'll get a nice green VALID logo. Failures will give an INVALID logo, and if there are errors parsing the specification or reaching it, an ugly red ERROR logo.
For example, using https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v2.0/json/petstore-expanded.json as a source, we get ...
If your specification fails to validate for some reason, or if there is an error, you can get more information on why by visiting https://validator.swagger.io/validator/debug?url={YOUR_URL}
.
Since the validator uses a browserless back-end to fetch the contents and schema, it's not subject to the terrible world of CORS.
You can also post a spec up to the service with CURL:
curl -X POST -d @swagger.json -H 'Content-Type:application/json' https://validator.swagger.io/validator/debug
In this example, swagger.json
is the swagger definition in JSON format, in the CWD.
Note that all the above is also applicable to OpenAPI 3.x specifications; for example, using https://petstore3.swagger.io/api/v3/openapi.json as a source, we get ...
Since version 2.1.0 a /parseByUrl
and /parseByContent
are available, returning a serialized parsed specification, with parsing and result configurable by
parameters, e.g. passing resolve
, etc. See Swagger Parser
Running locally
You can build and run the validator locally:
mvn package jetty:run
And access the validator like such:
http://localhost:8080/validator?url={URL}
or
http://localhost:8080/validator?url=http://petstore.swagger.io/v2/swagger.json
http://localhost:8080/validator?url=https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml
Security contact
Please disclose any security-related issues or vulnerabilities by emailing [email protected], instead of using the public issue tracker.