根据 Swagger API 模式验证 JSON

Validating JSON against Swagger API schema

提问by Peter G.

I created an API spec from some JSON files and I am trying to test if the files validate against the API spec.

我从一些 JSON 文件创建了一个 API 规范，我正在尝试测试这些文件是否根据 API 规范进行了验证。

There are some good tools to validate against JSON Schema, but I did not have chance to find a tool to validate against specs created in the Swagger (tool for creating API schema). The only solution I found is generating a client/server in the Swagger-Editor, it is quite cumbersome.

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

Is there already an existing tool to validate JSON against Swagger Schema?

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

采纳答案by mgold

Arnaud in the comments is correct that there are two separate questions here.

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

Do you want to validate that your spec is a valid OpenAPI (fka. Swagger) spec

您想验证您的规范是否是有效的 OpenAPI (fka. Swagger) 规范

You can

你可以

• Copy your spec to the online Swagger editorand it will throw errors. A quick dive through the sourcedoesn't tell me what it's using to create those errors, but it doesn't seem to be contacting a server to do it...
• Use the official swagger-parserfor Java.
• Use the unofficial swagger-parserfor JavaScript (browser or Node).

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

or validate that an implementation of this spec would produce JSON which is valid regarding your JSON schemas?

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

In other words, here's some JSON from a request or response body, is it correct?

换句话说，这是来自请求或响应主体的一些 JSON，它正确吗？

Swagger relies on another standard called JSON Schema for its schema objects, which are what actually describes the JSON (rather than endpoints or metadata). Swagger uses a subset of JSON Schema (missing: oneOf, patternProperties, among others). To that end, you can use a JSON Schema validator. There are 37 listed here; I'll give a shoutout to this online validatorthat also supports YAML schemas.

Swagger 依赖另一个称为 JSON Schema 的标准作为其schema objects，它们实际上描述了 JSON（而不是端点或元数据）。Swagger 使用 JSON Schema 的一个子集（缺少：oneOf，，patternProperties等等）。为此，您可以使用 JSON 模式验证器。这里列出了 37 个；我将对这个也支持 YAML 模式的在线验证器大喊大叫。

But, when I said Swagger relies on a subset of JSON API, I lied. There are a handful of fixed fields that have special meaning in Swagger that's not part of JSON Schema. One of them is discriminatorwhich is used for polymorphism. I am not aware of a Swagger validator that can process discriminator. There are a fair number of toolsfor swagger and some claim to do validations, but many are abandonware, meant for old versions, not feature-complete, tied to other technologies, and so on. If there's a mature and well-maintained library that I'm missing, I'd love to know.

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

回答by josephpconley

If your Swagger JSON is hosted, you could use the following url: http://online.swagger.io/validator/debug?url=your_url

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

回答by Michael

The OpenAPI 2.0 / Swagger schema is available in a few places, it's just a bit hard to find because of the heavy use of the word 'schema' in swagger itself.

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

• The 'official' home appears to be http://swagger.io/v2/schema.json
• Probably sourced from OpenAPI's repo: https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v2.0/schema.json
• On schemastore (which has a bunch more!): http://json.schemastore.org/swagger-2.0

• “官方”主页似乎是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

So you can point a generic validator at this schema and your document. For example, this works nicely for me using vscode and Red Hat's YAML extension.

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

回答by Bastien Jansen

Atlassian's swagger-request-validatoris a Java library that can do such validation:

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

A Java library for validating request/responses against a OpenAPI / Swagger specification. Includes support for Swagger v2 and OpenAPI v3 specifications and adapters for common mock and testing libraries.

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

The core library is not tied to any specific HTTP library, but they also provide additional modules that integrate with Spring MVC, MockMVC, REST Assured etc.

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

There is also swagger-schema-validatorthat can validate a JSON document against a Swagger V2 definition (disclaimer: I'm the author). This Java library is less complete than Atlassian's though.

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