根据Swagger API模式验证JSON

Question

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

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

是否已经有现成的工具可以验证JSON是否符合Swagger Schema？

- Peter G.

---

你想验证你的规范是否是有效的OpenAPI（曾用名Swagger）规范，还是验证该规范的实现将生成符合你的JSON模式的有效JSON？ - Arnaud Lauret

这个问题仅涉及检查一个 JSON 是否符合 OpenAPI 规范。 - Peter G.

你看过https://medium.com/@betz.mark/validate-json-models-with-swagger-and-bravado-5fad6b21a825吗？ - Prasanna K Rao

Swagger验证器节点包（https://www.npmjs.com/package/swagger-validation）似乎也很合适。 - Prasanna K Rao

@PeterGerhat，你解决了这个问题吗？我没有看到任何令人满意的答案。 - Leo Gallucci

@PeterGerhat，你解决了这个问题吗？我也需要这个问题的答案。如果你有便捷的解决方案，请告诉我。 - Paramesh Korrakuti

Answer 1

阿尔诺在评论中正确指出这里有两个单独的问题。

您想验证您的规范是否是有效的OpenAPI（前身为Swagger）规范吗？

您可以：

• 将您的规范复制到在线Swagger编辑器，它会抛出错误。快速浏览源代码并没有告诉我它使用什么来产生这些错误，但它似乎不需要与服务器联系以执行此操作...
• 使用官方的Java swagger-parser。
• 使用非官方的JavaScript（浏览器或Node）swagger-parser。

还是验证该规范的实现将生成符合您的JSON模式的JSON？

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

Swagger依赖于另一项称为JSON Schema的标准进行其模式对象，这些对象实际上描述了JSON（而不是端点或元数据）。 Swagger使用JSON Schema的子集（缺少：oneOf，patternProperties等）。为此，您可以使用JSON Schema验证器。这里列出了37个验证器；我要向这个在线验证器致敬，它还支持YAML模式。

但是，当我说Swagger依赖于JSON API的子集时，我撒谎了。在Swagger中，有一些固定的字段具有特殊意义，这些字段不属于JSON Schema的范畴。其中之一是discriminator，用于多态性。 我不知道是否有可以处理discriminator的Swagger验证器。 有一些Swagger工具可以进行验证，但其中许多都已被废弃，只适用于旧版，功能不完整，与其他技术绑定等等。如果有成熟且维护良好的库我不知道的话，我很想知道。

- mgold

---

我遇到了相同的情况，这篇文章很有帮助。经过一些努力，我能够编写自己的脚本来验证我的服务器响应负载与Swagger定义的JSON Schema是否匹配。我编写了一些Express中间件来实现这个功能。现在我可以使用Swagger所依赖的模式对象来完成我想要的操作，而不是试图让Swagger来做这件事。谢谢！ - Tina

第二个问题，如果不使用外部模式验证器，我该如何实现它？我只想针对（swagger）模式验证一个模式的实例。我该怎么做呢？谢谢。 - Nikhita Raghunath

从内部来看，Swagger似乎使用了Z-Schema JSON验证器，因此理论上您可以查看该验证器以了解可用的功能。https://github.com/zaggino/z-schema - chrismarx

这个解决方案对我没有用。故意删除了路径参数声明并进行了测试。它没有抱怨路径参数丢失。它只是验证 JSON 格式是否正确。 - Paramesh Korrakuti

是的，开放 API 模式（Swagger）不等同于 JSON 模式。Swagger 模式有一些扩展关键词，这些关键词不受 json schema 标准支持。 您可以查看 Swagger 文档： https://swagger.io/docs/specification/data-models/keywords/ - Klyuch

Answer 2

Atlassian的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的库功能更少。

- Bastien Jansen

---

这个库有没有C＃版本或等效物？ - A X

这个 Atlassian 库没有检查多态和继承。 - user190245

Answer 3

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

- josephpconley

---

这仅适用于可以通过互联网访问的URL。对于Intranet URL，这将无法工作。 - Paramesh Korrakuti

Answer 4

使用Java进行Swagger验证

使用https://github.com/bjansen/swagger-schema-validator，可以通过最小的Java代码对一个.json负载文件进行离线验证，以确保其符合一个.yaml Swagger规范：

1. 按照swagger-schema-validator自述文件中的说明，在您自己的项目中引用依赖项，或者使用git clone https://github.com/bjansen/swagger-schema-validator.git将其克隆到本地。

2. 将您的.yaml和.json文件复制到测试根目录下的src/test/resources文件夹中。

3. 创建一个测试类，其中包含以下内容（请确保将"/definitions/MyPayloadObjectMustBeSetHere"更改为指向您自己的定义）：

import com.github.bjansen.ssv.SwaggerValidator;
import com.github.fge.jsonschema.core.report.ProcessingReport;
import static org.junit.jupiter.api.Assertions.assertEquals;

@Test
void SwaggerSpecTest() {
    InputStream spec = getClass().getResourceAsStream("/api/swagger.yaml");
    SwaggerValidator validator = SwaggerValidator.forYamlSchema(new InputStreamReader(spec));

    InputStreamReader sample = new InputStreamReader(getClass().getResourceAsStream("/api/payload.json"));
    ProcessingReport report = validator.validate(CharStreams.toString(sample), "/definitions/MyPayloadObjectMustBeSetHere");
    assertEquals("success", report.toString()); // force printing the errors/warnings
}

- ccpizza

Answer 5

OpenAPI 2.0 / Swagger 架构在多个位置可用，只是由于 Swagger 中单词“schema”的频繁使用，有点难找。

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

因此，您可以将通用验证器指向此架构和文档。例如，对于我来说，这在使用 vscode 和红帽 YAML 扩展时非常有效。

- Michael