首页 文章

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

提问于
浏览 次
60

我使用Swagger v 1.2为服务提供了Swagger API声明

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

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

问题：是否有任何现有项目或一段代码，哪些可以 generate usable JSON Schema from Swagger API Declaration ？

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

swagger jsonschema

5 回答

  • 2

    经过长时间使用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尚未发布） .

    纠正问题导致真正的解决方案

    好问题解决了一半的问题 . 我的问题是错的，因为它错过了实现我的真实期望 . 更正的问题是：

    What specification framework and technique to use, to specify REST API using payload defined by arbitrary JSON Schema Draft 4 or W3C XML Schema 1.0.

    我对这个问题的回答是：

    • 使用JSON Schema Draft 4或W3C XML Schema设计有效负载

    • 通过RAML描述您的REST API（目前为v0.8） .

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

    回复于
  • 65

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

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

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

    回复于
  • 4

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

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

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

    希望这可以帮助 .

    回复于
  • 3

    刚发现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

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

    回复于
  • 1

    我这样做有一些成功：

    swagger.yaml - > proto - > jsonschema

    我使用openapi2proto从Swagger yaml生成proto文件，然后protoc-gen-jsonschema从中生成JSONSchemas . 它's good enough to get a typed JSONSchema, but proto3 doesn' t支持"required"类型，所以你错过了这个 .

    回复于

相关问题