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

Question

我使用Swagger v 1.2

为服务提供了Swagger API声明

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

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

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

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

Answer 1

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

Swagger仅支持JSON Schema Draft 4

的子集

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

• 我不能相信，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开始和结束。

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

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

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

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

如果需要完整的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。

我对这个问题的回答是：

1. 使用JSON Schema Draft 4或W3C XML Schema设计有效负载
2. 通过RAML（目前为v0.8）描述您的REST API。

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

Answer 2

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

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

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

Answer 3

有一个python工具可以通过名称openapi2jsonschema执行相同的操作。 您只需使用pip安装即可。

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

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

希望这有帮助。

Answer 4

刚刚发现了Swagger并问自己一样，因为这是一个要求。

找到了这个答案

  

直接从这里试试：

     

http://petstore.swagger.wordnik.com/

     

并将其作为您的网址：

     

http://petstore.swagger.wordnik.com/api/api-docs/pet

     

我看到了所有模特。不是吗？或者我错过了什么？

这里是他们的用户组： https://groups.google.com/forum/#!searchin/swagger-swaggersocket/schema/swagger-swaggersocket/bzxHxasWhQY/M35V1XWgm7EJ

问题是＆＃34;模型＆＃34;指有效的JSON模式4.0 / JSON超模式

Answer 5

我已经取得了一些成功：

swagger.yaml - ＆gt; proto - ＆gt; jsonschema

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