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


74

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

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

但是,虽然Swagger的一部分重用了JSON Schema结构,但事实证明,它仅使用功能的子集,并且还在Models中引入了它自己的继承(usingsubTypesdiscriminator)。

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

最佳JSON模式草案4,并使用Python(但我很乐意找到任何东西)。

Answers:


79

在使用Swagger指定REST API并在相关测试套件中重用它之后,我将分享自己的经验(回答我自己的问题)。

Swagger仅支持JSON Schema Draft 4的子集

Swagger 1.2和2.0状态的规范,它仅支持JSON Schema Draft 4的子集(此处为s。)。这意味着:

  • 不能相信Swagger可以完全支持每个有效的JSON模式。
  • 考虑到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模式是可行的,但并不容易

我花了一些时间编码一个库,该库将采用Swagger API规范并创建JSON Schema Draft4。出于以下几个原因,我放弃了:

  • 根本不容易
  • 令人失望的发现是,我只能使用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的外观非常漂亮等等)之外,它根本无法为上述更新的问题提供解决方案。


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

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

唯一的问题是RAML周围的社区仍然不够受欢迎。就像您所说的一样,如果Swagger允许完整的JSON模式,我可以通过用更好的python解析器替换pyswagger中的许多代码来删除它们。
mission.liao's

假设您的数据以JSON(而非XML)架构建模。使用RAML而不是JSON Hyper-Schema定义API的主要优势是什么?似乎缺少的功能列表将成为JSON Hyper-Schema draft-5的起点(假设该提案背后有一个社区)。
凯琳

10

有一个名为openapi2jsonschema的python工具可以做到这一点。您可以使用简单地安装它pip

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

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

希望这可以帮助。


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

6

我刚刚写了一个工具pyswagger似乎很适合您的需求。

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

这个工具可以解决我在python中使用Swagger时遇到的第一个问题,现在仍然很新。欢迎提出任何建议。


@missionliao第一印象非常好。在几周内,我将进行更详细的调查,发布我的应用程序(当前名为SwaggerProxy),我们可能会共同努力。您的解决方案中可见的一些设计决策也与我所做的非常相似,这是有希望的信号。
Jan Vlcinsky

1

这样我取得了一些成功:

swagger.yaml-> proto-> jsonschema

我使用openapi2proto从Swagger yaml生成原始文件,然后使用protoc -gen-jsonschema从中生成JSONSchemas。获得类型化的JSONSchema足够好,但是proto3不支持“必需”类型,因此您会错过这一点。

By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.