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
<?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 中创建主启动类：
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：
java
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 对象
*/
@Bean
public 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 中创建用户模型类：
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 和 Setters
public 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 中创建用户控制器：
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
properties
# 应用名称
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，且功能强大、易于维护。