根据 Swagger API 模式验证 JSON

Question

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

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

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

Answer 1

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

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

你可以

• 将您的规范复制到在线 Swagger 编辑器，它将引发错误。快速浏览源并没有告诉我它是用什么来创建这些错误的，但它似乎没有联系服务器来做到这一点......
• 使用官方的 Java swagger-parser。
• 使用非官方的 swagger-parser 用于 JavaScript（浏览器或 Node）。

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

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

Swagger 的“架构对象”依赖于另一个名为 JSON Schema 的标准，这些对象实际上描述了 JSON（而不是端点或元数据）。 Swagger 使用 JSON Schema 的子集（缺少：oneOf、

patternProperties

等）。为此，您可以使用 JSON 模式验证器。这里列出了

37个

；我要赞扬这个在线验证器，它也支持 YAML 模式。 但是，当我说 Swagger 依赖于 JSON API 的子集时，我撒了谎。有一些固定字段在 Swagger 中具有特殊含义，但不属于 JSON 架构的一部分。其中之一是

discriminator

，用于多态性。

我不知道有哪个 Swagger 验证器可以处理 

discriminator

。有大量用于 swagger 的工具，有些声称可以进行验证，但许多都是废弃软件，适用于旧版本，功能不完整，与其他技术相关，等等。如果我缺少一个成熟且维护良好的库，我很想知道。

Atlassian 的 swagger-request-validator

Answer 2

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

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

还有

swagger-schema-validator

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

如果您的 Swagger JSON 已托管，您可以使用以下 url：

http://online.swagger.io/validator/debug?url=your_url

Answer 3

使用 SpringBoot 和

atlassian-swagger-request-validator 进行 Swagger v3 验证

Answer 4

package com.mam.headless.openapi;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import com.atlassian.oai.validator.OpenApiInteractionValidator;
import com.atlassian.oai.validator.model.Request;
import com.atlassian.oai.validator.model.Response;
import com.atlassian.oai.validator.model.SimpleResponse;
import com.atlassian.oai.validator.report.ValidationReport;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@RestController
public class SwaggerValidator {
    @Operation(
            summary = "Validate JSON payload against Schema",
            description = "Validate provided JSON response string. "
                    + "Paste your JSON in the request body to check if it adheres to the schema rules."
    )
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Validation successful"),
            @ApiResponse(responseCode = "400", description = "Validation failed due to invalid JSON schema")
    })
    @PostMapping("/validate")
    public ResponseEntity<?> validateSchema(@RequestBody String jsonBody) {
        OpenApiInteractionValidator validator = OpenApiInteractionValidator.createForSpecificationUrl("http://localhost:8080/v3/api-docs").build();
        Response response = SimpleResponse.Builder
                .status(200)
                .withBody(jsonBody)
                .withContentType("application/json")
                .build();

        ValidationReport validationResult;
        try {
            validationResult = validator.validateResponse("/endpoint/path", Request.Method.GET, response);
            if (!validationResult.hasErrors()) {
                return new ResponseEntity<>(validationResult, HttpStatus.OK);
            } else {
                return new ResponseEntity<>(validationResult.getMessages(), HttpStatus.BAD_REQUEST);
            }
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(e.toString());
        }
    }
}

使用

swagger-schema-validator 进行 Swagger v2 验证

使用 https://github.com/bjansen/swagger-schema-validator:

根据

.json

 swagger 规范对 

.yaml

 负载文件进行离线验证的最少 Java 代码

参考

swagger-schema-validator

自述文件中所述的您自己项目中的依赖项，或使用
1. git clone https://github.com/bjansen/swagger-schema-validator.git

   在本地克隆。

   将
   .yaml
和
2. .json

   文件复制到测试根文件夹下的

   src/test/resources

   文件夹中。 创建一个包含一些内容的测试类（确保更改
   "/definitions/MyPayloadObjectMustBeSetHere"
以指向您自己的定义）：

3. 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
   }

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

Answer 5

“官方”主页似乎是

http://swagger.io/v2/schema.json

• 可能源自 OpenAPI 的存储库：https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v2.0/schema.json
• 在模式存储上（还有更多！）：http://json.schemastore.org/swagger-2.0
• 因此，您可以将此模式和您的文档指向通用验证器。例如，这对我使用 vscode 和 Red Hat 的 YAML 扩展非常有效。