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 对象
     */
    @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 中创建用户模型类：

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 中创建用户控制器：

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

1. 启动 DemoApplication 主类。
2. 访问以下 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，且功能强大、易于维护。