JSON输入对OpenAPI/Swagger模式进行验证：实用指南与工具

<dependencies>
    <dependency>
        <groupId>org.openapi4j</groupId>
        <artifactId>openapi-parser</artifactId>
        <version>1.0.9</version> <!-- 请使用最新稳定版本 -->
    </dependency>
    <dependency>
        <groupId>org.openapi4j</groupId>
        <artifactId>openapi-validator</artifactId>
        <version>1.0.9</version> <!-- 请使用最新稳定版本 -->
    </dependency>
</dependencies>

dependencies {
    implementation 'org.openapi4j:openapi-parser:1.0.9' // 请使用最新稳定版本
    implementation 'org.openapi4j:openapi-validator:1.0.9' // 请使用最新稳定版本
}

# openapi.yaml
openapi: 3.0.0
info:
  title: 用户管理API
  version: 1.0.0
paths:
  /users:
    post:
      summary: 创建新用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - age
              properties:
                name:
                  type: string
                  description: 用户姓名
                  minLength: 1
                age:
                  type: integer
                  description: 用户年龄
                  format: int32
                  minimum: 0
                  maximum: 150
                email:
                  type: string
                  description: 用户邮箱
                  format: email
                  nullable: true
      responses:
        '201':
          description: 用户创建成功
        '400':
          description: 无效的请求数据

import org.openapi4j.parser.OpenApi3Parser;
import org.openapi4j.parser.model.v3.OpenApi3;
import org.openapi4j.core.validation.ValidationResults;
import org.openapi4j.validator.OpenApiValidator;

import java.io.IOException;
import java.net.URL;
import java.nio.file.Paths;

public class JsonInputValidationTutorial {

    public static void main(String[] args) {
        // 1. 获取 OpenAPI/Swagger 模式定义文件的 URL
        // 假设 'openapi.yaml' 位于项目的 resources 目录下
        URL specUrl = JsonInputValidationTutorial.class.getClassLoader().getResource("openapi.yaml");
        if (specUrl == null) {
            System.err.println("错误：未找到 'openapi.yaml' 文件。请确保它位于 resources 目录下。");
            return;
        }

        OpenApi3 openApiSpec;
        try {
            // 2. 解析 OpenAPI 模式定义
            // OpenApi3Parser.parse() 方法会加载并解析 YAML/JSON 格式的 API 定义
            openApiSpec = new OpenApi3Parser().parse(Paths.get(specUrl.toURI()), false); // false 表示不进行模式本身的严格验证
        } catch (Exception e) {
            System.err.println("解析 OpenAPI 规范时发生错误: " + e.getMessage());
            e.printStackTrace();
            return;
        }

        // 3. 创建 OpenApiValidator 实例
        // 验证器需要 OpenAPI 规范对象和其基础 URI
        OpenApiValidator validator;
        try {
            validator = new OpenApiValidator(openApiSpec, specUrl.toURI());
        } catch (IOException e) {
            System.err.println("创建 OpenApiValidator 实例时发生错误: " + e.getMessage());
            e.printStackTrace();
            return;
        }

        // 4. 准备待验证的 JSON 输入数据
        String validJsonInput = "{\n" +
                                "  \"name\": \"张三\",\n" +
                                "  \"age\": 25,\n" +
                                "  \"email\": \"zhang.san@example.com\"\n" +
                                "}";

        String invalidJsonInput = "{\n" +
                                  "  \"name\": \"李四\",\n" +
                                  "  \"age\": -5, \n" + // 年龄为负数，违反 minimum: 0
                                  "  \"email\": \"invalid-email\"\n" + // 邮箱格式不正确
                                  "}";

        String missingRequiredFieldJsonInput = "{\n" +
                                               "  \"email\": \"wang.wu@example.com\"\n" + // 缺少 name 和 age 字段
                                               "}";

        // 5. 执行 JSON 输入验证
        System.out.println("--- 验证有效 JSON 输入 ---");
        performValidation(validator, validJsonInput, "/users", "post", "application/json");

        System.out.println("\n--- 验证无效 JSON 输入 (年龄为负，邮箱格式错误) ---");
        performValidation(validator, invalidJsonInput, "/users", "post", "application/json");

        System.out.println("\n--- 验证缺少必填字段的 JSON 输入 ---");
        performValidation(validator, missingRequiredFieldJsonInput, "/users", "post", "application/json");
    }

    /**
     * 执行JSON输入验证的辅助方法
     * @param validator OpenApiValidator 实例
     * @param jsonInput 待验证的 JSON 字符串
     * @param path API 路径 (例如 "/users")
     * @param method HTTP 方法 (例如 "post")
     * @param contentType 内容类型 (例如 "application/json")
     */
    private static void performValidation(OpenApiValidator validator, String jsonInput, String path, String method, String contentType) {
        try {
            // validate 方法用于验证请求体、响应体等
            // 它会根据 OpenAPI 规范中定义的路径、方法和内容类型来查找对应的模式进行验证
            ValidationResults results = validator.validate(jsonInput, path, method, contentType);

            if (results.has) {
                System.out.println("JSON 输入验证失败:");
                // 遍历并打印所有验证失败的信息
                results.forEach(result -> System.out.println("  - " + result.getMessage() + " (路径: " + result.getPointer() + ")"));
            } else {
                System.out.println("JSON 输入验证成功！");
            }
        } catch (IOException e) {
            System.err.println("验证过程中发生 IO 错误: " + e.getMessage());
            e.printStackTrace();
        }
    }
}