在使用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。
我对这个问题的回答是:
- 在JSON Schema Draft 4或W3C XML Schema中设计有效负载
- 通过RAML(目前为v0.8)描述您的REST API。
可能还有其他可用的规范框架,但是Swagger(无论v1.2还是v2.0)都不是这样。除了提供许多功能(代码生成,API的外观非常漂亮等等)之外,它根本无法为上述更新的问题提供解决方案。
swagger
->RAML
->JSON Schema