如何从Swagger API声明生成JSON-Schema [英] How to generate JSON-Schema from Swagger API Declaration
问题描述
我有使用 Swagger v 1.2
我对Swagger的最初感觉是，它非常接近JSON Schema(草案3和最近的Draft 4)，并且为请求和响应对象生成JSON Schema相对容易.
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.
但是，尽管Swagger的一部分重用了JSON Schema结构，但事实证明，它仅使用功能的子集，并且还在Models中引入了它自己的继承(使用subTypes和discriminator).
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) .
问题:是否存在任何现有项目或代码段，可以从Swagger API声明生成可用的JSON模式?
Question: Is there any existing project or piece of code, which can generate usable JSON Schema from Swagger API Declaration?
最佳JSON模式草案4，并使用Python(但我很乐意找到任何东西).
Optimally JSON Schema Draft 4 and using Python (but I will be happy to find anything).
推荐答案
在使用Swagger指定REST API并在相关测试套件中重用它之后，我将分享自己的经验(回答我自己的问题).
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).
Swagger 1.2和2.0状态的规范，它仅支持JSON模式草案4的子集(第此处).这意味着:
Specification of Swagger 1.2 and 2.0 states, it supports only subset of JSON Schema Draft 4 (s. here). This means, that:
- 一个人不能依靠，Swagger可以完全支持每个有效的JSON模式.
- 考虑XML，Swagger仅支持JSON Schema Draft 4提供的JSON结构子集的规范表示.
换句话说:
- Swagger(1.2和2.0)不支持使用许多JSON结构，这些结构对JSON Schema Draft 4而言是有效的(Draft 3也是如此).
- Swagger不支持常规XML数据结构，仅允许使用非常受限制的结构.
实际上，您不能以JSON或XML设计数据开始，而使用Swagger则必须以Swagger开头和结束.
In practice, you cannot start with designing your data in JSON or XML, with Swagger you have to start and end with Swagger.
我花了一些时间编码一个库，该库将采用Swagger API规范并创建JSON Schema Draft4.出于以下几个原因，我放弃了:
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:
- 这根本不容易
- 令人失望的发现是，我只能使用JSON Schema提供的子集.我们已经提出了一些JSON有效负载，因此不得不开始对其进行修改，以适应Swagger规范框架所允许的范围.
除了具有用于显示和测试API的非常漂亮的UI(是的，每个人都同意，这在视觉上非常令人愉悦)之外，我发现它很奇怪，规范框架不允许我们使用我们想要的东西，但是为我们的设计增加了意想不到的限制.
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.
研究其他API规范框架后，我发现了RAML.由于它是通过支持任何JSON Schema Draft 3/4或W3C XML Schema 1.0数据结构从头开始构建的，因此经验非常好-设计了有效负载的结构后，我能够非常快速地编写API规范并在验证实际请求之后并且对已定义模式的响应非常容易，因为模式是规范的基本组成部分，而没有对其施加任何限制.
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的版本为0.8(1.0版本尚未发布).
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:
使用哪种规范框架和技术，以使用由任意JSON Schema Draft 4或W3C XML Schema 1.0定义的有效负载来指定REST API.
我对这样一个问题的回答是:
My answer to such a question would be:
- 在JSON模式草案4或W3C XML模式中设计有效负载
- 通过RAML(目前为v0.8)描述您的REST API.
也许还有其他可用的规范框架，但是Swagger(无论是v1.2还是v2.0)绝对不是这种情况.除了提供许多功能(代码生成，API的外观非常漂亮等等)之外，它根本无法为上述更新的问题提供解决方案.
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.
这篇关于如何从Swagger API声明生成JSON-Schema的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
