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

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，且功能強大、易于維護。