在与使用 Swagger 指定 REST API 并在相关测试套件中重用它进行了长时间的斗争之后，我将分享我自己的经验（回答我自己的问题）。
Swagger 仅支持 JSON Schema Draft 4 的子集
Swagger 1.2 和 2.0 规范指出，它仅支持 JSON Schema Draft 4 的子集（第 4 章）。here https://github.com/OAI/OpenAPI-Specification/issues/156#issuecomment-59009462）。这意味着：
- 我们不能相信每个有效的 JSON Schema 都能被 Swagger 完全支持。
- 考虑到 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 架构支持，请使用 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 文档等等）之外，它根本无法为上述更新的问题提供解决方案。
