SpringBoot3整合SpringDoc實現(xiàn)在線接口文檔的詳細過程
寫在前面
在現(xiàn)目前項目開發(fā)中，一般都是前后端分離項目。前端小姐姐負責(zé)開發(fā)前端，苦逼的我們負責(zé)后端開發(fā)
事實是一個人全干，在這過程中編寫接口文檔就顯得尤為重要了。然而作為一個程序員，最怕的莫過于自己寫文檔和別人不寫文檔
大家都不想寫文檔，那這活就交給今天的主角Swagger來實現(xiàn)了
一、專業(yè)名詞介紹
①OpenApi是什么？
解答：OpenApi是一個用于描述、定義和共享 RESTful API 文檔的規(guī)范。最新規(guī)范是 OpenAPI 3.0
② Swagger是什么？
解答： Swagger 是一個用于設(shè)計和測試 RESTful APIs 的工具。
它提供了API 描述、請求和響應(yīng)示例、API 測試和文檔生成等豐富的功能。最新版本是Swagger3,支持OpenAPI3.0規(guī)范
③ SpringFox 是什么？
SpringFox 是 Spring 社區(qū)維護的一個項目（非官方），幫助使用者將 Swagger 2 集成到 Spring 中。
目前國內(nèi)項目使用的都是它
github地址：https://github.com/springfox/springfox
④springDoc是什么？
解答： Spring-doc也是 Spring 社區(qū)維護的一個項目（非官方），幫助使用者將 Swagger 3 集成到 Spring 中
SpringDoc 支持 Swagger 頁面 Oauth2 登錄，相較于 SpringFox 而言，它的支撐時間更長，無疑是更好的選擇。
但是在國內(nèi)發(fā)展較慢，網(wǎng)上一找資料，出來的基本上是 Swagger2的內(nèi)容。
⑤ OpenAPI 、Spring-doc和 Swagger 之間的關(guān)系
解答：OpenAPI 定義了一種標準的格式來表示 API 文檔，而 Swagger 是一個實現(xiàn) OpenAPI 規(guī)范的工具
二、Swagger詳細簡介
Swagger 江湖人稱“絲襪哥”，是一個幫助程序員生成接口文檔的利器。
只需要簡單配置，就可以生成帶有漂亮UI界面的接口文檔，而且編寫的接口代碼變了
接口文檔隨之也跟著變，做到了真正的解放雙手。
官網(wǎng)https://swagger.io/
Swagger 優(yōu)點
號稱世界上最流行的API框架
Restful Api文檔在線自動生成器- 直接運行，支持在線測試
API - 不僅僅支持Java，還支持多種語言（如：
PHP、Python、Node.js等）
三、小試牛刀
說了這么多Swagger 的優(yōu)點，接下來就小試牛刀，看看怎么將Swagger集成到SpringBoot中。
3.1、環(huán)境介紹
JDK：17SpringBoot：3.3.0Springdoc
注： 細心的小伙伴可能已經(jīng)發(fā)現(xiàn)了，在springboot3.0之前我用的都是Springfox來集成Swagger管理我們的API接口文檔,
但是Springfox已經(jīng)停止更新了，我們使用的是SpringBoot3 +jdk17 的環(huán)境后，Spring官網(wǎng)推薦了Springdoc 來整合swagger
3.2 新建一個springboot-web項目
3.3 添加依賴
由于篇幅原因，其他web項目相關(guān)依賴這里就不一一貼出來了。
第一個依賴是必須的，而且版本必須大于2.0.0
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.2.0</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
<version>2.2.0</version>
</dependency>注：
我們這里使用的是jdk17+springboot3.3.0 環(huán)境，原來swagger的V2和V3都不能用了，小伙伴們一定更要注意這兒
如果引入上面錯誤的依賴，項目啟動會報下面錯誤，這時候我們引入上面正確的依賴重新啟動項目即可
3.4 編寫HelloController
新建一個controller包--->建立一個HelloController類
@RestController
public class HelloController {
@RequestMapping("/hello")
public String hello(){
return "hello";
}
}我們在瀏覽器中輸入“http://localhost:8080/hello” 后回車，出現(xiàn)如下界面，說明我們的hello開發(fā)成功了
3.5 訪問swagger接口頁面
注：我們這里采用的是openapi ,所以就不用像swagger的V2和v3那樣添加配置類了
瀏覽器直接輸入：http://localhost:8080/swagger-ui/index.html 回車即可看到下面界面
整合swagger是不是很簡單呢
四、修改接口
從上面截圖中我們看到，我們在HelloController 中只定義了一個接口，但是前端UI界面中出來個7種請求方式（GET、PUT、POST、DELETE、OPTIONS、HEAD、PATCH）的接口，這是為什么呢？
解答：@RequestMapping("/hello") 我們接口中只是指定了訪問地址，并沒有指定請求方式
我們將注解修改成@RequestMapping(path = "/hello",method = RequestMethod.GET)
或者@GetMapping("/hello") 然后重啟服務(wù)，我們看到界面上就只有一種請求方式的接口了
五、接口文檔常用配置
5.1 配置訪問路徑
在application.yml中可以自定義api-docs和swagger-ui的訪問路徑。當(dāng)然了，如果沒配置，默認就是下面路徑
springdoc:
api-docs:
path: /v3/api-docs
swagger-ui:
path: /swagger-ui.html5.2 配置接口文檔基本信息
① 配置接口基本信息
新建一個config包--->并在包下建立一個SpringDocConfig配置類
② 配置接口文檔基礎(chǔ)信息
我們在配置類中添加如下代碼，
@Configuration
public class SpringDocConfig {
@Bean
public OpenAPI openAPI() {
return new OpenAPI()
// 配置接口文檔基本信息
.info(this.getApiInfo())
;
}
private Info getApiInfo() {
return new Info()
// 配置文檔標題
.title("SpringBoot3集成Swagger3")
// 配置文檔描述
.description("SpringBoot3集成Swagger3示例文檔")
// 配置作者信息
.contact(new Contact().name("程序員小凡").url("https://www.xiezhrspace.cn").email("1666397814@163.com"))
// 配置License許可證信息
.license(new License().name("Apache 2.0").url("https://www.xiezhrspace.cn"))
// 概述信息
.summary("SpringBoot3集成Swagger3示例文檔aaa")
.termsOfService("https://www.xiezhrspace.cn")
// 配置版本號
.version("2.0");
}
}前端頁面訪問接口文檔頁面后顯示如下
② 配置接口servers信息
接口可能存在多環(huán)境，如開發(fā)環(huán)境、測試環(huán)境、生產(chǎn)環(huán)境等
我們可以通過@OpenAPIDefinition 配合servers 屬性來配置不同環(huán)境，具體配置示例如下
@OpenAPIDefinition(
servers = {
@Server(description = "開發(fā)環(huán)境服務(wù)器", url = "http://localhost:8080"),
@Server(description = "測試環(huán)境服務(wù)器", url = "https://test.xiezhr.com")
}
)
@Configuration
public class SpringDocConfig {
//...
}配置完成后，瀏覽器訪問顯示如下
③ 配置外部文檔信息
有時候我們需要在在線接口文檔中可以顯示跳轉(zhuǎn)到API的一些外部文檔（比如 項目部署文檔等）
這個時候我們可以通過@OpenAPIDefinition 配合 externalDocs 屬性來配置外部文檔
具體配置如下
@OpenAPIDefinition(
externalDocs = @ExternalDocumentation(
description = "項目編譯部署說明",
url = "http://localhost:8080/deplay/readme.md"
)
)
@Configuration
public class SpringDocConfig {
//......
}配置完后重啟服務(wù)，瀏覽器訪問接口文檔，顯示如下
SpringDocConfig 類完整配置代碼如下
@OpenAPIDefinition(
servers = {
@Server(description = "開發(fā)環(huán)境服務(wù)器", url = "http://localhost:8080"),
@Server(description = "測試環(huán)境服務(wù)器", url = "https://test.xiezhr.com")
},
externalDocs = @ExternalDocumentation(
description = "項目編譯部署說明",
url = "http://localhost:8080/deplay/readme.md"
)
)
@Configuration
public class SpringDocConfig {
@Bean
public OpenAPI openAPI() {
return new OpenAPI()
// 配置接口文檔基本信息
.info(this.getApiInfo())
;
}
private Info getApiInfo() {
return new Info()
// 配置文檔標題
.title("SpringBoot3集成Swagger3")
// 配置文檔描述
.description("SpringBoot3集成Swagger3示例文檔")
// 配置作者信息
.contact(new Contact().name("程序員小凡").url("https://www.xiezhrspace.cn").email("1666397814@163.com"))
// 配置License許可證信息
.license(new License().name("Apache 2.0").url("https://www.xiezhrspace.cn"))
//
.summary("SpringBoot3集成Swagger3示例文檔aaa")
.termsOfService("https://www.xiezhrspace.cn")
// 配置版本號
.version("2.0");
}
}配置完上面信息后，重啟服務(wù)，瀏覽器訪問：http://localhost:8080/v3/swagger-ui/index.html
5.3 配置掃描接口
應(yīng)用場景：
有時候我們?yōu)榱藰I(yè)務(wù)需要，我們建立了多個包下的接口，如admin包下的，common包下的接口，
為了安全起見，我們只允許接口文檔中訪問comm包下面的接口。
在不加任何配置的情況下，所以接口都會默認顯示，具體如下
配置掃描接口包：
在application.yml中可以自定義要掃描的接口包
springdoc: packages-to-scan: com.xiezhr.swaggerdemo.common.controller
配置好之后重啟服務(wù)，我們發(fā)現(xiàn)前臺UI只顯示了common包下面的接口了
5.4 配置接口文檔開關(guān)
使用場景：
為了接口安全，我們一般需要在測試（test）環(huán)境或者開發(fā)(dev)環(huán)境中開啟接口文檔，而在生產(chǎn)（prod）環(huán)境中 關(guān)閉接口文檔
這個應(yīng)該怎么做呢？
這里涉及到SpringBoot多環(huán)境配置，忘記的小伙伴可以翻一翻之前的文章。傳送門：
我們創(chuàng)建三個配置文件，分別為
- ①
application-dev.yml開發(fā)環(huán)境 - ②
application-test.yml測試環(huán)境 - ③
application-prod.yml生產(chǎn)環(huán)境
只需在①和②配置文件中添加如下配置
springdoc:
api-docs:
enabled: true而③配置文件中添加
springdoc:
api-docs:
enabled: false通過上面配置后，我們在開發(fā)和測試環(huán)境下：就能正常訪問http://localhost:8080/v3/swagger-ui/index.html#/
而在生產(chǎn)環(huán)境下就無法訪問，報如下錯誤
5.5 配置API分組
為了演示API分組，我們在controller包下面再建立admin包和common包，包下分別添加AdminController和CommonController接口類,結(jié)構(gòu)及代碼如下
① AdminController類
// AdminController
@RestController
@RequestMapping("/admin")
public class AdminController {
@GetMapping("/index")
public String admin(){
return "admin";
}
}② CommonController 類
@RestController
@RequestMapping("/common")
public class CommonController {
@GetMapping("/hello")
public String hello(){
return "hello";
}
}在默認情況（沒有分組）的情況下，所有包下接口都顯示在一一個默認組下面，如/common/* 和/admin/* 訪問路徑下的接口都顯示在一起，如下圖所示
這時，如果/common/* 下的接口比較多，/admin/* 下的接口也比較多，界面上顯示就很混亂
解決辦法就是添加分組信息，我們在SpringDocConfig 配置類中添加如下代碼,這樣就把接口分為了"common通用模塊組" 和"admin模塊組" 兩個組
@Bean("commonGroupApi")
public GroupedOpenApi webGroupApi() {
return GroupedOpenApi.builder().group("common通用模塊組")
.pathsToMatch("/common/**")
.build();
}
@Bean("adminGroupApi")
public GroupedOpenApi adminGroupApi() {
return GroupedOpenApi.builder().group("admin模塊組")
.pathsToMatch("/admin/**")
.build();
}重啟服務(wù)，再訪問http://localhost:8080/v3/swagger-ui/index.html 如下
5.6 配置接口信息
① @Tag 注解使用
對一個 operation 進行說明或定義的標簽，用在類或方法上，也可以用在 @OpenAPIDefinition 中定義標簽。
常用參數(shù)：
name: 名稱description: 接口描述信息
示例：
用在類上
@RestController
@RequestMapping("/common")
@Tag(name = "公共接口", description = "公共接口")
public class CommonController {
//......
}② @Operation 注解使用
用于說明方法用途，用在方法上。
參數(shù)：
summary：方法概要，方法的一個簡單介紹，建議 120 個字符內(nèi)description：方法描述，一般是很長的內(nèi)容hidden：是否隱藏
示例：
@GetMapping("/hello")
@Operation(summary = "hello接口", description = "hello接口描述" ,hidden = true)
public String hello(){
return "hello";
}③ @Parameter注解使用
用于說明方法參數(shù)，用在方法參數(shù)上。
參數(shù)：
name：指定的參數(shù)名in：參數(shù)位置，可選query、header、path或cookie，默認為空，表示忽略description：參數(shù)描述required：是否必填，默認為false
示例：
@GetMapping("/user/{id}")
public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用戶ID",required = true) @PathVariable("id") Integer id){
User user = userService.getUserById(id);
return user;
}前端頁面查看
④ @ApiResponse 注解使用
用于說明一個響應(yīng)信息，用在 @ApiResponses 中。
參數(shù)：
responseCode：HTTP 響應(yīng)碼description：描述
示例：
@GetMapping("/user/{id}")
@Operation(summary = "獲取用戶信息", description = "根據(jù)用戶ID獲取用戶信息")
@ApiResponses(value ={
@ApiResponse(responseCode = "200", description = "請求成功"),
@ApiResponse(responseCode = "404", description = "用戶不存在")
})
public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用戶ID",required = true) @PathVariable("id") Integer id){
User user = userService.getUserById(id);
return user;
}
完整配置
@RestController
@RequestMapping("/common")
@Tag(name = "公共接口", description = "公共接口")
public class CommonController {
@Autowired
private IUserService userService;
@GetMapping("/hello")
@Operation(summary = "hello接口", description = "hello接口描述" ,hidden = true)
public String hello(){
return "hello";
}
@GetMapping("/hi")
@Operation(summary = "hi接口", description = "hi接口描述")
public String Hi(){
return "Hi 程序員小凡";
}
@GetMapping("/user/{id}")
@Operation(summary = "獲取用戶信息", description = "根據(jù)用戶ID獲取用戶信息")
@ApiResponses(value ={
@ApiResponse(responseCode = "200", description = "請求成功"),
@ApiResponse(responseCode = "404", description = "用戶不存在")
})
public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用戶ID",required = true) @PathVariable("id") Integer id){
User user = userService.getUserById(id);
return user;
}
}重啟后，瀏覽器訪問http://localhost:8080/v3/swagger-ui/index.html 如下
5.7 配置實體信息
① 新建一個User實體類
@Data
public class User {
private String name;
private Integer age;
private String email;
private String address;
}② @Schema標簽使用
用于描述數(shù)據(jù)對象信息或數(shù)據(jù)對象屬性，比如各種POJO類及屬性，用在類或類屬性上。
參數(shù)：
name：屬性名稱description：屬性描述required：是否必須minLength：字符最小長度maxLength：字符最大長度
③使用示例：
@Data
@Schema(description = "用戶實體類",name = "User")
public class User {
@Schema(description = "用戶名",name = "name",minLength = 6,maxLength = 20,required = true)
private String name;
@Schema(description = "年齡",name = "age",required = true,minimum = "1",maximum = "100")
private Integer age;
@Schema(description = "郵箱",name = "email",required = true)
private String email;
@Schema(description = "地址",name = "address")
private String address;
}④ 瀏覽器訪問：http://localhost:8080/v3/swagger-ui/index.html ，我們看到配置的實體信息顯示出來了
六、接口調(diào)試
通過上面各種配置之后，我們的在線接口文檔基本上生成得差不多了。接下來我們就來說說怎么使用在線接口文檔進行接口測試
① 測試說明
在之前小節(jié)中我們開發(fā)了要給根據(jù)用戶ID 獲取用戶信息的接口getUser。我們現(xiàn)在要做的就是在前端UI界面中找到這個接口，
在開發(fā)環(huán)境下輸入用戶ID值，然后獲取用戶信息。
② 選擇組信息
【獲取用戶信息】這個接口在，common通用模塊組下面，所以我們第一步就要前端UI界面右上角選擇這個組
② 選擇開發(fā)環(huán)境
在Servers 下選擇配置好的開發(fā)環(huán)境
③ 找到我們要測試的接口
④ 測試接口，獲取響應(yīng)數(shù)據(jù)
接口右邊下三角箭頭展開接口------>點擊Try it out
輸入?yún)?shù)：用戶ID------> 點擊【Execute】----->在Response body 中查看接口響應(yīng)信息
七、添加請求頭
很多時候我們接口都需要認證之后才能訪問，這時候我們就需要接口調(diào)用的時候攜帶著Token信息
示例：
我們通過@RequestHeader 注解 獲取請求頭中token信息
@GetMapping("/index")
public String admin(@RequestHeader ("token") String token){
System.out.println("token>>>>>>>>>>>>>>>>>>>>>>>>"+token);
//token 驗證
//.....各種業(yè)務(wù)邏輯
return "admin";
}
本文來自博客園，作者：xiezhr，轉(zhuǎn)載請注明原文鏈接：https://www.cnblogs.com/xiezhr/p/18253311
到此這篇關(guān)于SpringBoot3整合SpringDoc實現(xiàn)在線接口文檔的文章就介紹到這了,更多相關(guān)SpringBoot3在線接口文檔內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
使用proguard對maven構(gòu)建的springboot項目進行混淆方式
文章介紹了如何使用ProGuard對Maven構(gòu)建的Spring Boot項目進行混淆,并解決混淆后可能遇到的版本兼容性問題和類名沖突問題,主要步驟包括下載高版本的ProGuard、配置POM文件、添加ProGuard配置文件、修改Spring Boot啟動文件以避免類名沖突2024-11-11
這篇文章主要介紹了實體類或?qū)ο笮蛄谢瘯r,忽略為空屬性的操作，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2021-06-06
Java中HashMap與String字符串互轉(zhuǎn)的問題解決
本文介紹了Java中HashMap與String字符串互轉(zhuǎn)的問題解決，當(dāng)我們有需求將HashMap轉(zhuǎn)為Json格式的String時，需要使用FastJson/Gson將HashMap轉(zhuǎn)為String，感興趣的可以了解一下2022-03-03
深入分析Comparable與Comparator及Clonable三個Java接口
接口不是類，而是對類的一組需求描述，這些類要遵從接口描述的統(tǒng)一格式進行定義，這篇文章主要為大家詳細介紹了Java的Comparable,Comparator和Cloneable的接口，文中示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下，希望能夠給你帶來幫助2022-05-05
JAVA-4NIO之Channel之間的數(shù)據(jù)傳輸方法
下面小編就為大家?guī)硪黄狫AVA-4NIO之Channel之間的數(shù)據(jù)傳輸方法。小編覺得挺不錯的，現(xiàn)在就分享給大家，也給大家做個參考。一起跟隨小編過來看看吧2017-06-06
這篇文章主要介紹了Spring Security登錄驗證流程源碼解析,本文結(jié)合源碼講解登錄驗證流程，非常不錯，具有一定的參考借鑒價值，需要的朋友可以參考下2019-11-11
Spring Boot 把配置文件和日志文件放到j(luò)ar外部
如果不想使用默認的application.properties，而想將屬性文件放到j(luò)ar包外面，怎么做呢？下面小編給大家?guī)砹藘煞N方法解決Spring Boot 把配置文件和日志文件放到j(luò)ar外部問題，感興趣的朋友一起看看吧2018-02-02
解決OpenFeign遠程調(diào)用返回的對象總是null問題
OpenFeign在SpringCloud中用于遠程調(diào)用,配置簡單,在使用Ribbon或Hystrix時,需要注意path參數(shù)必須以/開頭,否則回參會是null2024-11-11
鎖像synchronized同步塊一樣，是一種線程同步機制，但比Java中的synchronized同步塊更復(fù)雜。因為鎖（以及其它更高級的線程同步機制）是由synchronized同步塊的方式實現(xiàn)的，所以我們還不能完全擺脫synchronized關(guān)鍵字2021-10-10
Mybatis-plus和Mybatis出現(xiàn)版本不兼容的問題解決
MyBatis-Plus?與?MyBatis?之間的兼容性問題通常是由于版本不匹配引起的,本文主要介紹了Mybatis-plus和Mybatis出現(xiàn)版本不兼容的問題解決,具有一定的參考價值,感興趣的可以了解一下2024-08-08