Swagger2與Springdoc集成與使用詳解
更新時(shí)間：2025年05月23日 14:33:06 作者：codingPower
這篇文章主要介紹了Swagger2與Springdoc集成與使用方式,具有很好的參考價(jià)值,希望對(duì)大家有所幫助,如有錯(cuò)誤或未考慮完全的地方,望不吝賜教
以下是將 Swagger2 遷移到 Springdoc（支持 OpenAPI 3）的集成與使用指南，涵蓋關(guān)鍵步驟、配置示例及注意事項(xiàng)：
1. 依賴配置
Springdoc 是支持 OpenAPI 3 規(guī)范的現(xiàn)代工具，適用于 Spring Boot 項(xiàng)目。
需替換或添加以下依賴：
<!-- Maven 依賴 -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.2.0</version> <!-- 使用最新版本 -->
</dependency>注意：若項(xiàng)目原使用 springfox-swagger2，需移除相關(guān)依賴以避免沖突。
2. 基礎(chǔ)配置
2.1 啟用 Springdoc
Springdoc 自動(dòng)配置，無(wú)需顯式啟用注解。
在 application.properties 或 application.yml 中配置基本信息：
# application.properties springdoc.swagger-ui.enabled=true springdoc.api-docs.path=/api-docs springdoc.swagger-ui.path=/swagger-ui.html springdoc.version=1.0.0 springdoc.default-produces-media-type=application/json
2.2 自定義 OpenAPI 信息
通過(guò) Java 配置類定義 API 元數(shù)據(jù)：
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("API 文檔")
.version("1.0")
.description("基于 Springdoc 的 OpenAPI 文檔")
.contact(new Contact().name("開發(fā)者").email("dev@example.com"))
.license(new License().name("Apache 2.0")));
}
}3. 注解使用
Springdoc 使用 io.swagger.v3.oas.annotations 注解替代 io.swagger.annotations。
常用注解對(duì)照表：
| Swagger2 注解 | Springdoc 注解 | 用途 |
|---|---|---|
| @Api | @Tag | 控制器分類描述 |
| @ApiOperation | @Operation | 接口方法描述 |
| @ApiParam | @Parameter | 方法參數(shù)描述 |
| @ApiModel | @Schema | 數(shù)據(jù)模型描述 |
| @ApiModelProperty | @Schema | 模型字段描述 |
| @ApiResponse | @ApiResponse | 接口響應(yīng)描述 |
示例代碼：
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
@RestController
@Tag(name = "用戶管理", description = "用戶相關(guān)操作接口")
@RequestMapping("/users")
public class UserController {
@Operation(summary = "獲取用戶詳情", description = "根據(jù)用戶ID查詢?cè)敿?xì)信息")
@GetMapping("/{id}")
public User getUser(
@Parameter(description = "用戶ID", required = true) @PathVariable Long id) {
// 業(yè)務(wù)邏輯
}
}4. 訪問(wèn) Swagger UI
啟動(dòng)應(yīng)用后，通過(guò)以下 URL 訪問(wèn)交互式文檔界面：
Swagger UI: http://localhost:8080/swagger-ui.htmlOpenAPI JSON: http://localhost:8080/v3/api-docs
5. 高級(jí)配置
5.1 分組多套 API
為不同模塊配置多組 API 文檔：
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("public-apis")
.pathsToMatch("/api/public/**")
.build();
}
@Bean
public GroupedOpenApi adminApi() {
return GroupedOpenApi.builder()
.group("admin-apis")
.pathsToMatch("/api/admin/**")
.build();
}5.2 安全配置
集成 JWT 或 OAuth2 時(shí)，添加安全方案：
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.components(new Components()
.addSecuritySchemes("bearerAuth",
new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT")))
.info(/* 略 */);
}6. 與 Spring Security 集成
確保 Spring Security 允許訪問(wèn)文檔端點(diǎn)：
@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(auth -> auth
.requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
.anyRequest().authenticated()
);
return http.build();
}
}7. 遷移注意事項(xiàng)
- 移除舊依賴：徹底清除
springfox-swagger2和swagger-annotations。 - 注解替換：全局替換包路徑
io.swagger.annotations→io.swagger.v3.oas.annotations。 - 路徑變化：Swagger UI 的默認(rèn)路徑從
/swagger-ui/變?yōu)?/swagger-ui.html。
8. 常見(jiàn)問(wèn)題
Q1: 文檔頁(yè)面無(wú)法加載？
- 檢查依賴沖突：確保無(wú)
springfox殘留依賴。 - 驗(yàn)證路徑配置：確認(rèn)
springdoc.swagger-ui.path未被覆蓋。
Q2: 注解未生效？
- 包路徑正確性：確認(rèn)使用
io.swagger.v3.oas.annotations下的注解。 - 方法簽名匹配：
@Parameter需直接修飾參數(shù)或配合@RequestParam使用。
通過(guò)以上步驟，可快速將項(xiàng)目從 Swagger2 遷移至 Springdoc，并充分利用 OpenAPI 3 的新特性。
總結(jié)
以上為個(gè)人經(jīng)驗(yàn)，希望能給大家一個(gè)參考，也希望大家多多支持腳本之家。
相關(guān)文章
springboot項(xiàng)目打包發(fā)布部署的過(guò)程及jar和war的區(qū)別
Spring Boot使用了內(nèi)嵌容器，因此它的部署方式也變得非常簡(jiǎn)單靈活，可以將Spring Boot項(xiàng)目打包成JAR包來(lái)獨(dú)立運(yùn)行，Spring Boot項(xiàng)目既可以生成WAR包發(fā)布，也可以生成JAR包發(fā)布，那么它們有什么區(qū)別呢2022-11-11
Java的反射（reflection）機(jī)制是指在程序的運(yùn)行狀態(tài)中，可以構(gòu)造任意一個(gè)類的對(duì)象，可以了解任意一個(gè)對(duì)象所屬的類，可以了解任意一個(gè)類的成員變量和方法，可以調(diào)用任意一個(gè)對(duì)象的屬性和方法2022-03-03
學(xué)習(xí)spring事務(wù)與消息隊(duì)列
這篇文章主要為大家詳細(xì)介紹了spring事務(wù)與消息隊(duì)列,具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2016-10-10
java實(shí)現(xiàn)字符與Unicode碼轉(zhuǎn)換(附源碼)
在 Java 開發(fā)中,經(jīng)常需要在字符（char 或 String）與其對(duì)應(yīng)的Unicode 碼點(diǎn)（int）之間進(jìn)行相互轉(zhuǎn)換,下面小編就來(lái)和大家詳細(xì)介紹一下具體實(shí)現(xiàn)方法吧2025-07-07
Sentinel的熔斷降級(jí)、資源規(guī)則詳解與實(shí)例
這篇文章主要介紹了Sentinel的熔斷降級(jí)、資源規(guī)則詳解與實(shí)例,Sentinel是阿里巴巴開源的一款流量控制和熔斷降級(jí)的框架,它主要用于保護(hù)分布式系統(tǒng)中的服務(wù)穩(wěn)定性,Sentinel通過(guò)對(duì)服務(wù)進(jìn)行流量控制和熔斷降級(jí),可以有效地保護(hù)系統(tǒng)的穩(wěn)定性,需要的朋友可以參考下2023-09-09
這篇文章主要介紹了java異步寫日志到文件中實(shí)現(xiàn)代碼的相關(guān)資料,需要的朋友可以參考下2017-04-04
Spring Boot Async異步執(zhí)行任務(wù)過(guò)程詳解
這篇文章主要介紹了Spring Boot Async異步執(zhí)行任務(wù)過(guò)程詳解,文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2020-08-08
Springboot跨域CORS處理實(shí)現(xiàn)原理
這篇文章主要介紹了Springboot跨域CORS處理實(shí)現(xiàn)原理,文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2020-04-04
scope用來(lái)聲明容器中的對(duì)象所應(yīng)該處的限定場(chǎng)景或者說(shuō)該對(duì)象的存活時(shí)間，即容器在對(duì)象進(jìn)入其 相應(yīng)的scope之前，生成并裝配這些對(duì)象，在該對(duì)象不再處于這些scope的限定之后，容器通常會(huì)銷毀這些對(duì)象，這篇文章主要介紹了Spring中的Bean作用域,需要的朋友可以參考下2022-06-06
如何實(shí)現(xiàn)java遞歸 處理權(quán)限管理菜單樹或分類
這篇文章主要介紹了如何實(shí)現(xiàn)java遞歸 處理權(quán)限管理菜單樹或分類,文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2020-01-01