SpringBoot使用SpringDoc+OpenAPI3.0實現(xiàn)接口文檔自動生成
在前后端分離項目中，接口文檔是剛需。
傳統(tǒng)手寫文檔效率低、更新不及時、容易和代碼不一致，溝通成本極高。
SpringBoot 官方早已放棄舊版 SpringFox（Swagger2），轉(zhuǎn)而推薦更輕量、更強大的 SpringDoc + OpenAPI 3.0。
今天我們來實現(xiàn)接口文檔自動生成、在線調(diào)試、權(quán)限配置、分組管理、生產(chǎn)環(huán)境關(guān)閉。
一、為什么選 SpringDoc，而不是 Swagger2？
- 支持 OpenAPI 3.0 規(guī)范
（最新行業(yè)標準） - 兼容 SpringBoot 2.6x / 2.7x / 3.x
（Swagger不兼容高版本Boot） - 無侵入、零配置，不污染業(yè)務(wù)代碼
- 性能更好、體積更小
- 支持 SpringBoot 官方推薦
- UI 更美觀、調(diào)試更方便
二、核心依賴
直接在 pom.xml 添加，無需其他依賴：
<dependency> <groupId>org.springdocgroupId> <artifactId>springdoc-openapi-uiartifactId> <version>1.7.0version> <dependency>
SpringBoot 3.x 用這個：
<dependency> <groupId>org.springdocgroupId> <artifactId>springdoc-openapi-starter-webmvc-uiartifactId> <version>2.2.0version> <dependency>
三、啟動
引入依賴后，什么都不用配！
直接啟動項目，訪問地址：
http://localhost:8080/swagger-ui.html
就能看到全自動生成的接口文檔，支持：
- 自動掃描所有 Controller
- 自動解析參數(shù)、返回值
- 在線發(fā)送請求調(diào)試
- 自動展示實體類字段
四、相關(guān)配置
創(chuàng)建配置類 SpringDocConfig.java，定義文檔標題、描述、版本、作者：
importio.swagger.v3.oas.models.OpenAPI;
importio.swagger.v3.oas.models.info.Contact;
importio.swagger.v3.oas.models.info.Info;
importorg.springframework.context.annotation.Bean;
importorg.springframework.context.annotation.Configuration;
@Configuration
publicclassSpringDocConfig{
@Bean
publicOpenAPIspringShopOpenAPI(){
returnnewOpenAPI()
info(newInfo()
title("SpringBoot 實戰(zhàn)項目 API 文檔")
description("接口文檔自動生成 | 在線調(diào)試")
version("v1.0.0")
name("后端開發(fā)")
email("developer@demo.com")
)
);
}
}五、常用注解
SpringDoc 使用 OpenAPI 3 注解，比 Swagger 更簡潔。
1. 控制層注解
importio.swagger.v3.oas.annotations.Operation;
importio.swagger.v3.oas.annotations.tags.Tag;
@RestController
@RequestMapping("/user")
@Tag(name ="用戶管理模塊", description ="用戶增刪改查接口")
publicclassUserController{
@Operation(summary ="根據(jù)ID查詢用戶", description ="傳入用戶ID，返回用戶詳情")
@GetMapping("/{id}")
publicResult<User>getUserById(@PathVariableInteger id){
returnResult.success();
}
}2. 實體/參數(shù)注解
importio.swagger.v3.oas.annotations.media.Schema;
@Data
@Schema(description ="用戶信息實體")
publicclassUser{
@Schema(description ="用戶ID", example ="1001")
privateInteger id;
@Schema(description ="用戶名", example ="zhangsan")
privateString username;
}3. 隱藏接口
@Operation(hidden =true)
@GetMapping("/test")
publicStringtest(){
return"test";
}六、application.yml 增強配置
springdoc: api-docs: enabled:true# 是否開啟接口文檔（生產(chǎn)設(shè)為false） path: /v3/api-docs # 文檔JSON地址 swagger-ui: enabled:true# 是否開啟UI頁面 path: /swagger-ui.html # 訪問路徑 tags-sorter: alpha # 按字母排序 operations-sorter: alpha # 接口排序 packages-to-scan: com.demo.controller # 只掃描Controller包
? 生產(chǎn)環(huán)境務(wù)必關(guān)閉文檔：
springdoc.api-docs.enabled=false springdoc.swagger-ui.enabled=false
七、帶 Token 權(quán)限的接口調(diào)試
如果項目有登錄認證（Token/JWT），配置文檔自動帶請求頭：
@Bean
publicOpenAPIopenAPI(){
returnnewOpenAPI()
.info(newInfo()
title("API文檔")
version("v1.0")
)
// 添加全局Token請求頭
components(newComponents()
addSecuritySchemes("token",
newSecurityScheme()
type(SecurityScheme.Type.APIKEY)
in(SecurityScheme.In.HEADER)
name("token")
)
);
}頁面上直接輸入 Token，所有接口自動攜帶。
八、接口文檔效果
訪問：http://localhost:8080/swagger-ui.html
你會看到：
- 模塊分組清晰
- 接口說明完整
- 參數(shù)自動解析
- 支持在線調(diào)試
- 返回結(jié)構(gòu)自動展示（Result）
學會 SpringDoc，你再也不用手寫接口文檔，前后端對接效率直接翻倍！
以上就是SpringBoot使用SpringDoc+OpenAPI3.0實現(xiàn)接口文檔自動生成的詳細內(nèi)容，更多關(guān)于SpringBoot接口文檔自動生成的資料請關(guān)注腳本之家其它相關(guān)文章！
相關(guān)文章
基于tomcat8 編寫字符編碼Filter過濾器無效問題的解決方法
下面小編就為大家分享一篇基于tomcat8 編寫字符編碼Filter過濾器無效問題的解決方法，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2018-01-01
這篇文章主要介紹了淺談junit4單元測試高級用法，小編覺得挺不錯的，在這里分享給大家，需要的朋友可以參考下。2017-10-10
這篇文章主要介紹了Spring框架依賴注入方法示例，分享了三種方法示例，具有一定參考價值，需要的朋友可以了解下。2017-11-11
springboot使用ThreadPoolTaskExecutor多線程批量插入百萬級數(shù)據(jù)的實現(xiàn)方法
這篇文章主要介紹了springboot利用ThreadPoolTaskExecutor多線程批量插入百萬級數(shù)據(jù),本文通過示例代碼給大家介紹的非常詳細，對大家的學習或工作具有一定的參考借鑒價值，需要的朋友可以參考下2023-02-02
Java中的ScheduledThreadPoolExecutor定時任務(wù)詳解
這篇文章主要介紹了Java中的ScheduledThreadPoolExecutor詳解,??ScheduledThreadPoolExecutor?繼承自?ThreadPoolExecutor,它主要用來在給定的延遲之后運行任務(wù),或者定期執(zhí)行任務(wù),ScheduledThreadPoolExecutor?的功能與?Timer?類似<BR>,需要的朋友可以參考下2023-12-12
MyBatis實現(xiàn)多表聯(lián)合查詢resultType的返回值
這篇文章主要介紹了MyBatis多表聯(lián)合查詢resultType的返回值，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2022-03-03
基于Java實現(xiàn)一個復雜關(guān)系表達式過濾器
這篇文章主要為大家詳細介紹了如何基于Java實現(xiàn)一個復雜關(guān)系表達式過濾器。文中的示例代碼講解詳細，感興趣的小伙伴可以了解一下2022-07-07
SpringBoot中@Autowired注入service時出現(xiàn)循環(huán)依賴問題的解決方法
在Spring Boot開發(fā)過程中,@Autowired注入Service時出現(xiàn)循環(huán)依賴是一個常見問題,循環(huán)依賴指的是兩個或多個Bean相互依賴,形成閉環(huán),導致Spring容器無法正常初始化這些Bean,這里提供幾種解決Spring Boot中@Autowired注入Service時循環(huán)依賴問題的方法2024-02-02
這篇文章主要介紹了idea 多模塊項目依賴父工程class找不到問題的方法，小編覺得挺不錯的，現(xiàn)在分享給大家，也給大家做個參考。一起跟隨小編過來看看吧2019-01-01
Java使用POI從Excel讀取數(shù)據(jù)并存入數(shù)據(jù)庫(解決讀取到空行問題)
有時候需要在java中讀取excel文件的內(nèi)容,專業(yè)的方式是使用java POI對excel進行讀取,這篇文章主要給大家介紹了關(guān)于Java使用POI從Excel讀取數(shù)據(jù)并存入數(shù)據(jù)庫,文中介紹的辦法可以解決讀取到空行問題,需要的朋友可以參考下2023-12-12