11.Spring Boot 3.1.5 中使用 SpringDoc OpenAPI（替代 Swagger）生成 API 文档
Spring Boot 3.1.5 中使用 SpringDoc OpenAPI（替代 Swagger）生成 API 文档
1. 项目结构
假设项目名为 springboot-openapi-demo，以下是项目的基本结构：
springboot-openapi-demo/
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/
│ │ │ └── example/
│ │ │ └── demo/
│ │ │ ├── DemoApplication.java # 主启动类
│ │ │ ├── config/ # 配置类目录
│ │ │ │ └── OpenApiConfig.java # OpenAPI 配置类
│ │ │ ├── controller/ # 控制器目录
│ │ │ │ └── UserController.java # 示例控制器
│ │ │ └── model/ # 模型类目录
│ │ │ └── User.java # 用户模型类
│ │ └── resources/
│ │ └── application.properties # 配置文件
└── pom.xml # Maven 依赖配置
2. 创建 pom.xml 并添加依赖
在 pom.xml 中添加 Spring Boot 和 SpringDoc OpenAPI 的依赖：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.1.5</version><relativePath/> <!-- 查找父 POM 的位置 --></parent><groupId>com.example</groupId><artifactId>springboot-openapi-demo</artifactId><version>0.0.1-SNAPSHOT</version><name>springboot-openapi-demo</name><description>Spring Boot 3.1.5 + SpringDoc OpenAPI 示例</description><properties><java.version>17</java.version> <!-- 指定 JDK 17 --><springdoc-openapi.version>2.3.0</springdoc-openapi.version> <!-- SpringDoc 版本 --></properties><dependencies><!-- Spring Boot Web 依赖 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- SpringDoc OpenAPI UI 依赖（用于生成 Swagger UI） --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>${springdoc-openapi.version}</version></dependency></dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>
</project>
3. 创建主启动类 DemoApplication.java
在 src/main/java/com/example/demo/DemoApplication.java 中创建主启动类：
package com.example.demo;import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;/*** Spring Boot 主启动类* 用于启动整个应用*/
@SpringBootApplication
public class DemoApplication {public static void main(String[] args) {SpringApplication.run(DemoApplication.class, args);}
}
4. 创建 OpenAPI 配置类 OpenApiConfig.java
在 src/main/java/com/example/demo/config/OpenApiConfig.java 中配置 OpenAPI：
package com.example.demo.config;import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;/*** OpenAPI 配置类* 用于自定义 API 文档的元信息（如标题、描述、版本等）*/
@Configuration
public class OpenApiConfig {/*** 自定义 OpenAPI 实例* @return 配置好的 OpenAPI 对象*/@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("Spring Boot 3.1.5 API 文档") // API 文档标题.description("这是一个使用 SpringDoc OpenAPI 生成的示例 API 文档") // 描述.version("1.0") // 版本号.license(new License() // 许可证信息.name("Apache 2.0") // 许可证名称.url("https://www.apache.org/licenses/LICENSE-2.0"))); // 许可证 URL}
}
对应效果:
5. 创建用户模型类 User.java
(/swagger-ui/index.html和/v3/api-docs里都没看到这个类里的的信息，后面有需要可以研究研究)
在 src/main/java/com/example/demo/model/User.java 中创建用户模型类：
package com.example.demo.model;import io.swagger.v3.oas.annotations.media.Schema;/*** 用户实体类* 用于表示用户的基本信息*/
@Schema(description = "用户实体") // 描述该类的用途
public class User {@Schema(description = "用户 ID", example = "1") // 描述字段的用途和示例值private Long id;@Schema(description = "用户名", example = "john_doe")private String username;// Getters 和 Setterspublic Long getId() {return id;}public void setId(Long id) {this.id = id;}public String getUsername() {return username;}public void setUsername(String username) {this.username = username;}
}
6. 创建用户控制器 UserController.java
在 src/main/java/com/example/demo/controller/UserController.java 中创建用户控制器：
package com.example.demo.controller;import com.example.demo.model.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;/*** 用户管理控制器* 提供用户相关的 RESTful API*/
@RestController
@RequestMapping("/api/users") // 基础路径
@Tag(name = "用户管理", description = "用户相关的 API 接口") // 分类标签
public class UserController {/*** 根据用户 ID 获取用户信息* @param id 用户 ID* @return 用户信息字符串*/@GetMapping("/{id}")@Operation(summary = "获取用户信息", description = "根据用户 ID 获取用户详情") // 操作描述public String getUser(@PathVariable Long id) {return "User ID: " + id;}/*** 创建新用户* @param userData 用户数据（示例中为字符串，实际应为 User 对象）* @return 创建结果*/@PostMapping@Operation(summary = "创建用户", description = "创建新用户") // 操作描述public String createUser(@RequestBody String userData) {return "Created user: " + userData;}
}
对应效果:
7. 配置 application.properties
在 src/main/resources/application.properties 中添加基本配置：
F
# 应用名称
spring.application.name=springboot-openapi-demo# 服务器端口
server.port=8080# 日志配置（可选）
logging.level.org.springframework=INFO
8. 启动应用并访问 Swagger UI
- 启动
DemoApplication主类。 - 访问以下 URL 查看 Swagger UI：
http://localhost:8080/swagger-ui.html（SpringDoc 默认路径）- 或
http://localhost:8080/v3/api-docs（查看原始 OpenAPI 3.0 JSON）
9. 代码注释说明
- 类注释：
- 描述类的用途（如
User类表示用户实体）。
- 描述类的用途（如
- 方法注释：
- 描述方法的功能、参数和返回值（如
getUser方法根据 ID 获取用户）。
- 描述方法的功能、参数和返回值（如
- 注解注释：
- 解释注解的作用（如
@Tag用于分类 API，@Operation用于描述操作）。
- 解释注解的作用（如
- 配置类注释：
- 解释配置的作用（如
OpenApiConfig用于自定义 API 文档的元信息）。
- 解释配置的作用（如
10. 总结
- 依赖：使用
springdoc-openapi-starter-webmvc-ui替代springfox。 - 配置：通过
OpenApiConfig自定义 API 文档信息。 - 注解：使用
@Tag、@Operation等注解丰富 API 文档。 - 启动：访问
http://localhost:8080/swagger-ui.html查看文档。
这种方式完全兼容 Spring Boot 3.1.5 和 JDK 17，且功能强大、易于维护。