如何在Spring Boot构建/运行时自动验证OpenAPI .yaml规范文件？

方案1：使用swagger-maven-plugin #

这个插件可以在Maven构建的指定阶段自动验证你的OpenAPI YAML文件，配置简单，能在构建初期就发现规范问题。只需在pom.xml的build/plugins中添加如下配置，将验证绑定到validate阶段：

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>2.2.10</version> <!-- 使用最新稳定版 -->
    <executions>
        <execution>
            <phase>validate</phase>
            <goals>
                <goal>validate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <inputSpec>${project.basedir}/src/main/resources/specification.yaml</inputSpec>
        <outputPath>${project.build.directory}/swagger-validator</outputPath>
        <swaggerVersion>3.0</swaggerVersion> <!-- 对应你的OpenAPI版本 -->
    </configuration>
</plugin>

执行mvn validate或包含该阶段的构建命令（如mvn clean install）时，插件会自动校验YAML的语法与规范合规性，一旦出错就终止构建并抛出详细提示。

方案2：使用openapi-validator-maven-plugin #

这是专门针对OpenAPI规范的验证插件，支持2.0和3.x版本，功能更聚焦：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-validator-maven-plugin</artifactId>
    <version>2.1.0</version> <!-- 最新稳定版 -->
    <executions>
        <execution>
            <id>validate-openapi</id>
            <phase>validate</phase>
            <goals>
                <goal>validate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <inputSpec>${project.basedir}/src/main/resources/specification.yaml</inputSpec>
        <failOnError>true</failOnError> <!-- 验证失败时终止构建 -->
    </configuration>
</plugin>

如果构建阶段验证无法满足需求，也可以在项目启动时自动验证OpenAPI文件，借助Swagger Core依赖实现：

1. 先在pom.xml中添加Swagger Core依赖：

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-core</artifactId>
    <version>2.2.15</version> <!-- 最新稳定版 -->
</dependency>

2. 编写启动时验证组件，用@PostConstruct注解在Spring容器初始化时执行验证：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.parser.OpenAPIV3Parser;
import io.swagger.v3.parser.core.models.SwaggerParseResult;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Component;

import javax.annotation.PostConstruct;
import java.io.IOException;
import java.nio.charset.StandardCharsets;

@Component
public class OpenApiSpecValidator {

    @PostConstruct
    public void validateOpenApiSpec() throws IOException {
        // 读取resources下的specification.yaml文件
        ClassPathResource resource = new ClassPathResource("specification.yaml");
        String specContent = new String(resource.getInputStream().readAllBytes(), StandardCharsets.UTF_8);

        // 解析并验证规范
        SwaggerParseResult result = new OpenAPIV3Parser().readContents(specContent);
        if (!result.getMessages().isEmpty()) {
            // 验证失败时抛出异常，阻止项目启动
            throw new IllegalStateException("OpenAPI规范验证失败：" + String.join("; ", result.getMessages()));
        }
    }
}

项目启动时会自动加载并验证YAML文件，一旦有错误就会直接启动失败，避免带着无效规范运行。

内容的提问来源于stack exchange，提问作者IvanNickSim