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

Posted 2023-02-15

【中文标题】如何从 Swagger API 声明生成 JSON-Schema

【英文标题】：How to generate JSON-Schema from Swagger API Declaration

【发布时间】：2014-07-29 20:57:27

【问题描述】：

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

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

然而，虽然 Swagger 的一部分重用了 JSON Schema 结构，但事实证明它只使用了一部分功能，并且还在模型中引入了自己的继承（使用 subTypes 和 discriminator）。

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

最佳 JSON Schema Draft 4 并使用 Python（但我很乐意找到任何东西）。

【参考方案1】：

将 OpenApi 安装到 Jsonschema 提取器：

打开终端 - 执行以下命令

sudo yum install python-pip
pip install openapi2jsonschema

将 openApi yaml 文件下载到文件夹

cd 到下载的文件夹然后运行这个命令

openapi2jsonschema --strict <openapi yaml filename>

【参考方案2】：

在与使用 Swagger 指定 REST API 并在相关测试套件中重用它的长期斗争之后，我将分享我自己的经验（回答我自己的问题）。

Swagger 仅支持 JSON Schema Draft 4 的子集

Swagger 1.2 和 2.0 状态的规范，它仅支持 JSON Schema Draft 4 的子集（s.here）。这意味着：

不能相信，每个有效的 JSON Schema 都可以被 Swagger 完全支持。 考虑到 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 开始和结束。

理论上可以获取 JSON Schema，但并不容易

我花了一些时间编写一个库，该库将采用 Swagger API 规范并创建 JSON Schema Draft 4。我放弃了有几个原因：

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

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

如果您想要完整的 JSON 或 XML Schema 支持，请使用 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。

我对这样一个问题的回答是：

在 JSON Schema Draft 4 或 W3C XML Schema 中设计您的负载 通过 RAML（目前为 v0.8）描述您的 REST API。

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

【讨论】：

那里有一些 Swagger 到 RAML 的转换器。 @jan-vlcinsky 您认为这适用于“简单”模式吗？ swagger -> RAML -> JSON Schema

@webwurst 听起来很有希望。您是否知道任何将 RAML 转换为 JSON Schema 的工具？还是转换为 RAML 已经为元素构建了 JSON Schema？无论如何，我对 Swagger 的主要问题是错误的期望，即在 Swagger 中我可以表达 JSON Schema 允许的任何内容，但事实并非如此。

唯一的问题是围绕 RAML 的社区还不够流行。就像你说的那样，如果 Swagger 允许完整的 JSON 模式，我可以通过用更好的 python 解析器替换它们来删除 pyswagger 中的几十个代码。

假设您的数据以 JSON（而非 XML）模式建模。使用 RAML 而不是 JSON Hyper-Schema 来定义 API 的主要优势是什么？似乎缺少的功能列表将成为 JSON Hyper-Schema Draft-5 的起点（假设该提案背后有一个社区）。

【参考方案3】：

有一个名为openapi2jsonschema 的python 工具可以做同样的事情。 您可以使用pip 简单地安装它。

openapi2 的自述文件显示了使用它的最简单方法：

openapi2jsonschema https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json

希望这会有所帮助。

【讨论】：

这也适用于离线 yaml open api 规范。

【参考方案4】：

我已经成功地这样做了：

swagger.yaml -> 原型 -> jsonschema

我使用 openapi2proto 从 Swagger yaml 生成 proto 文件，然后使用 protoc-gen-jsonschema 从中生成 JSONSchema。获得一个类型化的 JSONSchema 就足够了，但是 proto3 不支持“必需”类型，所以你会错过这个。

【参考方案5】：

我刚刚写了一个工具pyswagger 似乎适合你的需要。

它加载 Swagger API 声明，并能够将 python 对象 转换为/从 Swagger 原语。还提供一组客户端实现（包括 requests 和 tornado.httpclient.AsyncHTTPClient），可以直接向启用 Swagger 的服务发出请求。

这个工具倾向于解决我在python中适配Swagger时遇到的第一个问题，现在还是很新。欢迎提出任何建议。

【讨论】：

@missionliao 第一印象非常好。几周后我会来更详细地调查它，发布我的应用程序（目前名为 SwaggerProxy），我们可能会加入我们的努力。您的解决方案中可见的一些设计决策与我所做的非常相似，这是一个很有希望的信号。