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

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

我对Swagger的原始感觉是,它非常接近JSON模式(草案3和最近的草案4),并且对请求和响应对象生成JSON模式相对容易。

然而,尽pipeSwagger的一部分重用了JSON Schema结构,但它只使用了一部分function,并且还在Models中引入了它自己的inheritance(使用子subTypesdiscriminator )。

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

最佳的JSON模式草案4和使用Python(但我会很高兴find任何东西)。

经过长时间的使用Swagger来指定REST API并在相关的testing套件中重用它,我会分享我自己的经验(回答我自己的问题)。

Swagger仅支持JSON模式草案4的子集

Swagger 1.2和2.0状态的规范,它只支持JSON Schema Draft 4的子集。这意味着:

  • 不能依靠,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来devise数据,Swagger必须以Swagger开始和结束。

获取JSON模式在理论上是可行的,但并不容易

我花了一些时间编码一个库,这将需要Swagger API规范和创buildJSON模式草案4.我放弃了几个原因:

  • 这并不容易
  • 得到失望的发现,我可以只使用JSON模式提供的子集。 我们已经提出了一些JSON负载,并且不得不开始修改它,以适应Swagger规范框架允许的。

除了展示和testingAPI的真正漂亮的用户界面(是的,大家都同意,这在视觉上非常令人愉快),我发现它很奇怪,规范框架不允许我们使用我们想要的,但增加了意想不到的限制到我们的devise。

如果您想要完整的JSON或XML Schema支持,请使用RAML

研究其他的API规范框架,我发现了RAML。 由于它是通过支持任何JSON Schema Draft 3/4或W3C XML Schema 1.0数据结构从头开始构build的,所以体验非常好 – devise了我的有效负载的结构,我可以非常快速地创buildAPI规范,并在validation实际请求之后对定义模式的响应非常容易,因为模式是规范的基本组成部分,而不会对其添加任何限制。

当时的RAML版本是0.8(版本1.0还没有发布)。

纠正问题导致真正的解决scheme

好的问题可以解决一半的问题。 我的问题错了,因为它错过了我真正的期望。 更正的问题将是:

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

我对这个问题的回答是:

  1. 在JSON Schema Draft 4或W3C XML Schema中devise您的有效载荷
  2. 用RAML(目前是v0.8)描述你的REST API。

可能还有其他的规范框架可用,但Swagger(v1.2和v2.0都不是这样)。 除了提供真正的许多function(代码生成,非常漂亮的API文档以及更多)之外,它只是无法提供上述更新问题的解决scheme。

刚刚发现了Swagger,并问自己这是一个要求。

find了这个答案

从这里直接尝试:

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

并把它作为你的url:

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

我看到所有的模型。 你不是吗? 还是我错过了什么?

在他们的用户组中: https : //groups.google.com/forum/#!searchin/swagger-swaggersocket/schema/swagger-swaggersocket/bzxHxasWhQY/M35V1XWgm7EJ

问题是如果“模型”是指有效的JSON模式4.0 / JSON超模式

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

它加载Swagger API声明,并能够将Python对象转换为/来自Swagger基元 。 还提供一组客户端实现(包括请求tornado.httpclient.AsyncHTTPClient ),可以直接向启用Swagger的服务发出请求。

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

我已经取得了一些成功,像这样:

swagger.yaml – > proto – > jsonschema

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