I have Swagger API Declaration for services using Swagger v 1.2
My original feeling about Swagger was, that it is very close to JSON Schema (Draft 3 and lately Draft 4) and it shall be relatively easy to generate JSON Schema for request and response objects.
However, while part of the Swagger reuses JSON Schema structures, it turned out, it uses only subset of features, and it also introduces it's own inheritance in Models (using subTypes
and discriminator
) .
Question: Is there any existing project or piece of code, which can generate usable JSON Schema from Swagger API Declaration?
Optimally JSON Schema Draft 4 and using Python (but I will be happy to find anything).
After longer fight with using Swagger for specifying REST API and reusing it in related test suites, I will share my own experience with it (answering my own question).
Specification of Swagger 1.2 and 2.0 states, it supports only subset of JSON Schema Draft 4 (s. here). This means, that:
In other words:
In practice, you cannot start with designing your data in JSON or XML, with Swagger you have to start and end with Swagger.
I have spent some time coding a library, which would take Swagger API Specification and create JSON Schema Draft 4. I gave up for couple of reasons:
Apart from having really nice looking UI for showing and testing the API (yes, everybody agrees, it is visually very pleasing), I have found it weird, that a specification framework is not allowing us to use what we want, but adds unexpected restrictions to our design.
Researching other API specification frameworks, I have found RAML. As it is built from ground up by supporting any JSON Schema Draft 3/4 or W3C XML Schema 1.0 data structures, the experience was excellent - having structure of my payload designed, I was able authoring API specification very quickly and following validation of real requests and responses against defined schemas was very easy, as the schemas are essentials components of the specification without adding any restrictions on them.
RAML was at version 0.8 that time (version 1.0 was not released yet).
Good question makes half of the solution. My question was wrong as it missed fulfilling my real expectations. Corrected question would be:
What specification framework and technique to use, to specify REST API using payload defined by arbitrary JSON Schema Draft 4 or W3C XML Schema 1.0.
My answer to such a question would be:
There might be other specification frameworks usable, but Swagger (neither v1.2 nor v2.0) is definitely not the case. Apart from providing really a lot of features (code generation, very nice looking documentation of the API and much more), it simply fails in providing solution to the updated question stated above.