swagger - 如何从 Swagger API 声明生成 JSON-Schema

Question

我有使用 Swagger v 1.2 的服务的 Swagger API 声明.

我对 Swagger 的最初感觉是它非常接近 JSON Schema(Draft 3 和最近的 Draft 4)，并且为请求和响应对象生成 JSON Schema 应该相对容易。

然而，虽然 Swagger 部分重用了 JSON Schema 结构，但事实证明它只使用了功能的子集，并且还在 Models 中引入了自己的继承(使用 subTypes 和 鉴别器)。

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

最好是 JSON Schema Draft 4 并使用 Python(但我很乐意找到任何东西)。

Answer 1

在与使用 Swagger 指定 REST API 并在相关测试套件中重用它进行了长时间的斗争之后，我将分享我自己的经验(回答我自己的问题)。

Swagger 仅支持 JSON 架构草案 4 的子集

Swagger 1.2 和 2.0 规范指出，它仅支持 JSON Schema Draft 4 的子集(第 here )。这意味着:

• 不能相信每个有效的 JSON 架构都能得到 Swagger 的完全支持。
• 考虑到 XML，Swagger 仅支持 JSON 架构草案 4 提供的 JSON 结构子集的规范表示。

换句话说:

• Swagger(1.2 和 2.0)不支持使用许多 JSON 结构，这些结构在 JSON 架构草案 4 中有效(这同样适用于草案 3)。
• Swagger 不支持一般 XML 数据结构，仅允许非常受限的结构。

实际上，您不能从使用 JSON 或 XML 设计数据开始，而使用 Swagger 必须以 Swagger 开始和结束。

获取 JSON Schema 理论上是可能的，但并不容易

我花了一些时间编写一个库，该库将采用 Swagger API 规范并创建 JSON 架构草案 4。我放弃了几个原因:

• 这并不容易
• 失望地发现，我只能使用 JSON Schema 提供的子集。我们已经提出了一些 JSON 有效负载，并且必须开始修改它以适应 Swagger 规范框架允许的内容。

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

如果您想要完整的 JSON 或 XML 架构支持，请使用 RAML

在研究其他API规范框架时，我发现了RAML。由于它是通过支持任何 JSON Schema Draft 3/4 或 W3C XML Schema 1.0 数据结构从头开始构建的，因此体验非常好 - 设计了有效负载的结构后，我能够非常快速地编写 API 规范并跟踪真实请求的验证对已定义模式的响应非常容易，因为模式是规范的基本组成部分，无需对其添加任何限制。

当时 RAML 是 0.8 版本(1.0 版本尚未发布)。

纠正问题会带来真正的解决方案

好的问题就是解决方案的一半。我的问题是错误的，因为它未能满足我的真实期望。更正的问题是:

使用什么规范框架和技术来指定使用由任意 JSON Schema Draft 4 或 W3C XML Schema 1.0 定义的负载的 REST API。

我对这个问题的回答是:

1. 采用 JSON 架构草案 4 或 W3C XML 架构设计负载
2. 通过 RAML(目前为 v0.8)描述您的 REST API。

可能还有其他可用的规范框架，但 Swagger(无论是 v1.2 还是 v2.0)绝对不是这样。除了提供很多功能(代码生成、非常漂亮的 API 文档等等)之外，它根本无法为上述更新的问题提供解决方案。