我有使用 Swagger v 1.2.

I have Swagger API Declaration for services using Swagger v 1.2.

我对 Swagger 的最初感觉是它非常接近 JSON Schema(草案 3 和最近的草案 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 和 鉴别器).

However, while part of the Swagger reuses JSON Schema structures, it turned out that it uses only a subset of features, and it also introduces its own inheritance in Models (using subTypes and discriminator).

问题:是否有任何现有的项目或代码可以从 Swagger API 声明生成可用的 JSON Schema?

Question: Is there any existing project or piece of code which can generate usable JSON Schema from Swagger API Declaration?

最佳 JSON Schema Draft 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 Schema Draft 4 的子集(s. 这里).这意味着:

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 Schema.考虑到 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 Draft 4.我放弃了几个原因:

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 规范框架所允许的.

除了有非常漂亮的 UI 来显示和测试 API(是的，每个人都同意，它在视觉上非常令人愉悦)，我觉得很奇怪，规范框架不允许我们使用我们想要的东西，但是为我们的设计添加了意想不到的限制.

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 Schema Draft 4 或 W3C XML Schema 中设计您的负载通过 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.