针对 Swagger API 模式验证 JSON

Posted 2023-02-15

【中文标题】针对 Swagger API 模式验证 JSON

【英文标题】：Validating JSON against Swagger API schema

【发布时间】：2017-01-09 14:22:18

【问题描述】：

我从一些 JSON 文件创建了一个 API 规范，我正在尝试测试这些文件是否符合 API 规范。

有一些很好的工具可以验证 JSON 模式，但我没有机会找到一个工具来验证 Swagger 中创建的规范（用于创建 API 模式的工具）。我找到的唯一解决方案是在 Swagger-Editor 中生成客户端/服务器，这很麻烦。

是否已有工具可以根据 Swagger Schema 验证 JSON？

【问题讨论】：

您想验证您的规范是有效的 OpenAPI (fka. Swagger) 规范还是验证该规范的实现会生成对您的 JSON 模式有效的 JSON？

问题仅在于检查 JSON 是否符合 OpenAPI 规范。

你看过medium.com/@betz.mark/…吗？

Swagger 验证器节点包 (npmjs.com/package/swagger-validation) 看起来也很合适。

@PeterGerhat 你解决了吗？我没有看到任何令人满意的答案。

【参考方案1】：

您可以使用 OpenAPI validation 验证 OpenAPI 架构是否支持 openAPI V3。

【参考方案2】：

Atlassian's swagger-request-validator 是一个可以进行此类验证的 Java 库：

用于根据 OpenAPI / Swagger 规范验证请求/响应的 Java 库。包括对 Swagger v2 和 OpenAPI v3 规范的支持以及用于常见模拟和测试库的适配器。

核心库不绑定到任何特定的 HTTP 库，但它们还提供与 Spring MVC、MockMVC、REST Assured 等集成的附加模块。

还有swagger-schema-validator 可以根据 Swagger V2 定义验证 JSON 文档（免责声明：我是作者）。不过，这个 Java 库不如 Atlassian 的完整。

【讨论】：

是否有这个库的 C# 端口或等价物？

【参考方案3】：

OpenAPI 2.0 / Swagger 架构在一些地方可用，只是有点难以找到，因为在 swagger 本身中大量使用了“架构”一词。

“官方”主页似乎是http://swagger.io/v2/schema.json 可能来自 OpenAPI 的 repo：https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v2.0/schema.json 在 schemastore 上（还有更多！）：http://json.schemastore.org/swagger-2.0

因此，您可以将通用验证器指向此架构和您的文档。例如，这对我使用 vscode 和 Red Hat 的 YAML 扩展非常有效。

【参考方案4】：

cmets 中的 Arnaud 是正确的，这里有两个单独的问题。

您是否要验证您的规范是有效的 OpenAPI（fka.Swagger）规范

你可以

将您的规范复制到online Swagger editor，它会抛出错误。快速浏览 source 并没有告诉我它是用什么来创建这些错误的，但它似乎并没有联系服务器来做这件事...... Java 使用官方swagger-parser。 对 javascript（浏览器或节点）使用非官方的 swagger-parser。

或验证此规范的实现是否会生成对您的 JSON 模式有效的 JSON？

换句话说，这是来自请求或响应正文的一些 JSON，是否正确？

Swagger 的 schema objects 依赖于另一个名为 JSON Schema 的标准，这实际上是描述 JSON（而不是端点或元数据）的内容。 Swagger 使用 JSON Schema 的子集（缺少：oneOf、patternProperties 等）。为此，您可以使用 JSON 模式验证器。有37 listed here；我会向同样支持 YAML 模式的 this online validator 致敬。

但是，当我说 Swagger 依赖于 JSON API 的一个子集时，我撒了谎。在 Swagger 中有一些具有特殊含义的固定字段不属于 JSON Schema。其中之一是discriminator，用于多态性。 我不知道可以处理 discriminator 的 Swagger 验证器。有一个 fair number of tools 表示招摇，有些声称会进行验证，但许多是废弃软件，适用于旧版本，功能不完整，与其他技术相关，等等。如果我缺少一个成熟且维护良好的库，我很想知道。

【讨论】：

我也有同样的情况，这很有帮助。通过一些工作，我能够编写自己的脚本，该脚本可以使用 Swagger 定义的 JSON Schema 验证我的服务器的响应负载。我写了一些 Express 中间件来做到这一点。我可以使用它所依赖的模式对象，而不是尝试使用 Swagger 来做我想做的事。谢谢！

对于第二个，如果不使用外部模式验证器，我将如何实现它？我只想根据（招摇）模式验证模式的实例。我该怎么做？谢谢。

在内部看起来像 swagger 正在使用 z-schema json 验证器，所以理论上你会看看有哪些功能可用？ github.com/zaggino/z-schema

这个解决方案对我不起作用。故意删除路径参数声明并进行测试。它没有抱怨路径参数错过了。它只是验证格式良好的 json 与否。

【参考方案5】：

如果您的 Swagger JSON 是托管的，您可以使用以下网址： http://online.swagger.io/validator/debug?url=your_url

【讨论】：

这仅适用于可通过互联网访问的 url。这不适用于 Intranet url。