Validating JSON against Swagger API schema

问题:

I created an API spec from some JSON files and I am trying to test if the files validate against the API spec.

There are some good tools to validate against JSON Schema, but I did not have chance to find a tool to validate against specs created in the Swagger (tool for creating API schema). The only solution I found is generating a client/server in the Swagger-Editor, it is quite cumbersome.

Is there already an existing tool to validate JSON against Swagger Schema?

回答1:

Arnaud in the comments is correct that there are two separate questions here.

Do you want to validate that your spec is a valid OpenAPI (fka. Swagger) spec

You can

• Copy your spec to the online Swagger editor and it will throw errors. A quick dive through the source doesn't tell me what it's using to create those errors, but it doesn't seem to be contacting a server to do it...
• Use the official swagger-parser for Java.
• Use the unofficial swagger-parser for JavaScript (browser or Node).

or validate that an implementation of this spec would produce JSON which is valid regarding your JSON schemas?

In other words, here's some JSON from a request or response body, is it correct?

Swagger relies on another standard called JSON Schema for its schema objects, which are what actually describes the JSON (rather than endpoints or metadata). Swagger uses a subset of JSON Schema (missing: oneOf, patternProperties, among others). To that end, you can use a JSON Schema validator. There are 37 listed here; I'll give a shoutout to this online validator that also supports YAML schemas.

But, when I said Swagger relies on a subset of JSON API, I lied. There are a handful of fixed fields that have special meaning in Swagger that's not part of JSON Schema. One of them is discriminator which is used for polymorphism. I am not aware of a Swagger validator that can process discriminator. There are a fair number of tools for swagger and some claim to do validations, but many are abandonware, meant for old versions, not feature-complete, tied to other technologies, and so on. If there's a mature and well-maintained library that I'm missing, I'd love to know.

回答2:

If your Swagger JSON is hosted, you could use the following url: http://online.swagger.io/validator/debug?url=your_url

回答3:

The OpenAPI 2.0 / Swagger schema is available in a few places, it's just a bit hard to find because of the heavy use of the word 'schema' in swagger itself.

• The 'official' home appears to be http://swagger.io/v2/schema.json
• Probably sourced from OpenAPI's repo: https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v2.0/schema.json
• On schemastore (which has a bunch more!): http://json.schemastore.org/swagger-2.0

So you can point a generic validator at this schema and your document. For example, this works nicely for me using vscode and Red Hat's YAML extension.

回答4:

Atlassian's swagger-request-validator is a Java library that can do such validation:

A Java library for validating request/responses against a OpenAPI / Swagger specification. Includes support for Swagger v2 and OpenAPI v3 specifications and adapters for common mock and testing libraries.

The core library is not tied to any specific HTTP library, but they also provide additional modules that integrate with Spring MVC, MockMVC, REST Assured etc.

There is also swagger-schema-validator that can validate a JSON document against a Swagger V2 definition (disclaimer: I'm the author). This Java library is less complete than Atlassian's though.