Spring Boot项目生成OpenAPI服务端代码的依赖疑问

为什么需要额外添加swagger-annotations依赖 #

openapi-generator-maven-plugin 6.4.0生成的实体类代码中，会用到@Schema注解的requiredMode()方法来标记字段的必填模式。这个方法是在io.swagger.core.v3:swagger-annotations 2.0.0及以上版本才新增的。

你之前引入的org.openapitools:openapi-generator虽然间接依赖了swagger-annotations，但可能传递过来的版本较低（无requiredMode()方法），或者依赖传递被其他依赖覆盖，导致编译时找不到该方法。手动指定swagger-annotations:2.2.8，能确保生成的代码找到对应的注解方法，解决编译错误。

Spring Boot 2.7.5整合OpenAPI 3.0.3的规范方式 #

一、依赖配置（pom.xml）

核心依赖要保证版本兼容，避免依赖冲突：

<!-- OpenAPI注解支持 -->
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.2.8</version>
</dependency>
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-models</artifactId>
    <version>2.2.8</version>
</dependency>
<!-- 处理空值序列化，适配OpenAPI生成的模型 -->
<dependency>
    <groupId>org.openapitools</groupId>
    <artifactId>jackson-databind-nullable</artifactId>
    <version>0.2.6</version>
</dependency>
<!-- 可选：Swagger UI界面支持，适配Spring Boot 2.7.x -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version>
</dependency>

构建插件配置，确保生成符合Spring Boot风格的代码：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>6.4.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <!-- 你的OpenAPI 3.0.3规范文件路径 -->
                <inputSpec>${project.basedir}/src/main/resources/openapi.yml</inputSpec>
                <!-- 生成Spring Boot适配的代码 -->
                <generatorName>spring</generatorName>
                <configOptions>
                    <!-- 只生成API接口，不生成空实现类 -->
                    <interfaceOnly>true</interfaceOnly>
                    <!-- 禁用Spring Boot 3特性，适配2.7.x -->
                    <useSpringBoot3>false</useSpringBoot3>
                    <!-- 模型类包路径 -->
                    <modelPackage>com.yourproject.model</modelPackage>
                    <!-- API接口包路径 -->
                    <apiPackage>com.yourproject.api</apiPackage>
                    <!-- 可选：用Lombok简化模型类代码 -->
                    <useLombok>true</useLombok>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

二、代码生成与实现

1. 编写符合OpenAPI 3.0.3规范的openapi.yml文件，定义接口路径、请求参数、响应模型等
2. 执行Maven命令mvn clean generate-sources，自动生成API接口和模型类
3. 编写业务实现类，继承生成的API接口，实现具体逻辑

三、文档自定义配置

创建配置类，设置API文档的基础信息：

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.context.annotation.Configuration;

@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "业务系统API文档",
                version = "1.0.0",
                description = "包含用户管理、订单处理等核心接口"
        )
)
public class OpenApiConfig {
}

四、文档访问

启动应用后，通过以下地址访问：

• Swagger UI可视化界面：http://localhost:8080/swagger-ui.html
• OpenAPI规范原始JSON：http://localhost:8080/v3/api-docs

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