How to generate JSON schema from Swagger API declaration

Question

I have a Swagger API declaration for services using Swagger v 1.2

My initial feeling about Swagger was that it is very close to the JSON scheme (project 3 and the last project 4), and it is relatively easy to create a JSON scheme for request and response objects.

However, although part of Swagger reuses the JSON Schema structures, it turns out that it uses only a subset of the functions and also introduces its own inheritance in the Model (using subTypes and discriminator ).

Question: Is there any existing project or piece of code that can generate a useful JSON scheme from the Swagger API Declaration ?

Optimal is JSON Schema Draft 4 and using Python (but I would love to find something).

Answer 1

After a longer battle using Swagger to specify a REST API and reusing it in related test suites, I will share my own experience with it (answering my own question).

Swagger only supports a subset of JSON Draft 4 schema

The Swagger 1.2 and 2.0 state specification only supports a subset of JSON Schema Draft 4. This means that:

• you cannot rely on every valid JSON scheme to be fully supported by Swagger.
• thinking XML, Swagger only supports the canonical representation of a subset of the JSON structures provided by the JSON Draft 4 project.

In other words:

• Swagger (1.2 and 2.0) does not support the use of many JSON structures that are valid from the point of view of the JSON Draft 4 scheme (the same applies to project 3).
• Swagger does not support general XML data structures, only very limited structures are allowed.

In practice, you cannot start by developing your data in JSON or XML, and Swagger you need to start and end Swagger.

Getting a JSON schema is theoretically possible but not easy

I spent some time coding a library that would take the Swagger API specification and create a JSON Schema Draft 4 project. I gave up two reasons:

• that was not easy.
• got disappointed that I can only use a subset of what JSON Schema provides. We already had some kind of JSON payload, and I had to modify it to fit the specification of the Swagger specification.

Besides a really nice user interface for showing and testing the API (yes, everyone agrees, it is visually very nice), it seemed strange to me that the structure of the specification does not allow us to use what we want, but adds unexpected restrictions to our design.

If you need full JSON or XML Schema support, use RAML

Studying other API specifications, I found RAML. Since it was built from scratch, supporting any JSON Schema Draft 3/4 or W3C XML Schema 1.0 data structures, the experience was excellent - with the design of my payload I was able to quickly develop the API specification and after checking the real requests and the responses against certain schemes were very easy since schemas are important components of a specification without adding any restrictions to them.

RAML was in version 0.8 at the time (version 1.0 was not yet released).

Correcting the issue leads to a real solution.

A good question is half the solution. My question was wrong, as he missed fulfilling my real expectations. The corrected question:

What specification structure and technique to use to specify the REST API using the payload defined by an arbitrary JSON scheme 4 scheme or W3C XML scheme 1.0.

My answer to this question is:

• Build your payload in JSON Draft 4 or W3C XML Schema
• Describe your REST API using RAML (v0.8 at the moment).

There may be other specifications, but Swagger (neither v1.2 nor v2.0) is definitely not the same. Besides providing a really large number of functions (code generation, very nice API documentation, and much more), it simply fails to provide a solution to the updated issue mentioned above.

Answer 2

Swagger just opened and asked himself just as it would be a requirement.

Found this answer

Try it right here:

http://petstore.swagger.wordnik.com/

and specify this as your url:

http://petstore.swagger.wordnik.com/api/api-docs/pet

I see all the models. You do not? Or am I missing something?

here in his user group: https://groups.google.com/forum/#!searchin/swagger-swaggersocket/schema/swagger-swaggersocket/bzxHxasWhQY/M35V1XWgm7EJ

Question

is that if the "models" refer to a valid JSON 4.0 / JSON hyper-schema

Answer 3

I just wrote a pyswagger tool that suits you.

It loads the Swagger API declaration and is able to convert a python object to / from Swagger primitives . Also provide a set of client implementations (including requests and tornado.httpclient.AsyncHTTPClient ) that can directly access Swagger-enabled service.

This tool tends to solve the first problem that I encountered while adapting Swagger in python, and is still fairly new. Welcome to any suggestion.

Answer 4

I had some success doing it like this:

swagger.yaml → proto → jsonschema

I used openapi2proto to create proto files from Swagger yaml, then protoc-gen-jsonschema to generate JSONSchemas. This is good enough to get JSONSchema typed, but proto3 does not support the "required" types, so you will skip this.