SpringBoot+Swagger打造美觀API文檔的實(shí)戰(zhàn)指南
導(dǎo)語
在現(xiàn)代 Web 開發(fā)中，API 文檔是開發(fā)者和團(tuán)隊(duì)協(xié)作的重要組成部分。Swagger 作為一款強(qiáng)大的 API 文檔生成工具，能夠自動(dòng)生成直觀、可交互的接口文檔，提升開發(fā)效率。本文將詳細(xì)介紹如何在 Spring Boot 2 和 Spring Boot 3 中集成 Swagger，并展示多種接口文檔風(fēng)格，幫助開發(fā)者選擇適合自己項(xiàng)目的展示方式。
一、Swagger 簡(jiǎn)介
Swagger 是一個(gè)開源工具，用于生成、描述和可視化 RESTful API。它不僅能自動(dòng)生成 API 文檔，還提供交互式界面，方便開發(fā)者測(cè)試和調(diào)試接口。Swagger 與 Spring Boot 集成后，可以輕松管理和展示項(xiàng)目的 API。
二、Spring Boot 2 集成 Swagger
Spring Boot 2 中，常用的 Swagger 集成方案是基于 Springfox 庫(kù)。以下是具體步驟：
1. 添加依賴
在項(xiàng)目的 pom.xml 文件中添加以下依賴：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2. 配置 Swagger
創(chuàng)建一個(gè)配置類，例如 SwaggerConfig.java，啟用 Swagger 并定義文檔的基本信息：
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 指定掃描的包
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot 2 Swagger API")
.description("API documentation for Spring Boot 2 project")
.version("1.0.0")
.build();
}
}
3. 訪問 Swagger UI
啟動(dòng) Spring Boot 應(yīng)用后，打開瀏覽器訪問 http://localhost:8080/swagger-ui.html，即可看到生成的 API 文檔界面。
三、Spring Boot 3 集成 Swagger
Spring Boot 3 中，由于 Springfox 已不再積極維護(hù)，推薦使用 Springdoc OpenAPI 庫(kù)。它與 Spring Boot 3 的新特性（如 Jakarta EE）兼容，且配置更簡(jiǎn)單。
1. 添加依賴
在 pom.xml 中添加 Springdoc OpenAPI 的依賴：
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.9</version>
</dependency>
2. 配置 Swagger
Springdoc 默認(rèn)自動(dòng)啟用 Swagger UI，無需額外配置。但可以通過 application.properties 或 application.yml 自定義路徑和行為，例如：
# 自定義 Swagger UI 路徑 springdoc.swagger-ui.path=/swagger-ui.html # 自定義 API 文檔 JSON 路徑 springdoc.api-docs.path=/v3/api-docs
3. 訪問 Swagger UI
啟動(dòng)應(yīng)用后，訪問 http://localhost:8080/swagger-ui.html，即可查看 API 文檔。
四、多種接口文檔風(fēng)格展示
Swagger 提供了多種 UI 風(fēng)格，開發(fā)者可以根據(jù)需求選擇合適的展示方式。以下是幾種常見的風(fēng)格及其配置方法：
1. 默認(rèn) Swagger UI
Swagger UI 是最常用的風(fēng)格，提供交互式界面，支持 API 測(cè)試。Spring Boot 2 和 3 默認(rèn)集成后即可使用：
- Spring Boot 2：
http://localhost:8080/swagger-ui.html - Spring Boot 3：
http://localhost:8080/swagger-ui.html
2. Redoc
Redoc 是一個(gè)簡(jiǎn)潔、美觀的靜態(tài)文檔展示工具，適合生成靜態(tài) API 文檔。在 Spring Boot 3 中使用 Springdoc 配置：
在 application.properties 中添加：
# 禁用默認(rèn) Swagger UI springdoc.swagger-ui.enabled=false # 啟用 Redoc springdoc.redoc.enabled=true
訪問 http://localhost:8080/redoc，即可查看 Redoc 風(fēng)格的文檔。
3. Knife4j
Knife4j 是 Swagger 的增強(qiáng)版，提供更豐富的功能和更友好的界面，支持 Spring Boot 2 和 3。
在 Spring Boot 2 中集成 Knife4j
添加依賴：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>
修改配置類：
@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot 2 Knife4j API")
.description("API documentation with Knife4j")
.version("1.0.0")
.build();
}
}
訪問 http://localhost:8080/doc.html，即可體驗(yàn) Knife4j 界面。
在 Spring Boot 3 中集成 Knife4j
添加依賴：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
無需額外配置，啟動(dòng)應(yīng)用后訪問 http://localhost:8080/doc.html。
五、實(shí)戰(zhàn)示例
以下是一個(gè)簡(jiǎn)單的 Spring Boot 項(xiàng)目示例，展示如何使用 Swagger 注解生成詳細(xì)的 API 文檔。
1. 創(chuàng)建控制器
創(chuàng)建一個(gè)簡(jiǎn)單的 REST 控制器：
import org.springframework.web.bind.annotation.*;
import java.util.*;
@RestController
@RequestMapping("/api")
public class UserController {
@GetMapping("/users")
public List<String> getUsers() {
return Arrays.asList("Alice", "Bob");
}
@PostMapping("/users")
public String createUser(@RequestBody String user) {
return "Created: " + user;
}
}
2. 添加 Swagger 注解
為控制器和方法添加注解，提供更詳細(xì)的 API 描述：
Spring Boot 2（Springfox）
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.*;
@Api(tags = "User API")
@RestController
@RequestMapping("/api")
public class UserController {
@ApiOperation(value = "獲取所有用戶", notes = "返回用戶列表")
@GetMapping("/users")
public List<String> getUsers() {
return Arrays.asList("Alice", "Bob");
}
@ApiOperation(value = "創(chuàng)建新用戶", notes = "創(chuàng)建并返回新用戶")
@PostMapping("/users")
public String createUser(@RequestBody String user) {
return "Created: " + user;
}
}
Spring Boot 3（Springdoc）
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;
import java.util.*;
@Tag(name = "User API")
@RestController
@RequestMapping("/api")
public class UserController {
@Operation(summary = "獲取所有用戶", description = "返回用戶列表")
@GetMapping("/users")
public List<String> getUsers() {
return Arrays.asList("Alice", "Bob");
}
@Operation(summary = "創(chuàng)建新用戶", description = "創(chuàng)建并返回新用戶")
@PostMapping("/users")
public String createUser(@RequestBody String user) {
return "Created: " + user;
}
}
3. 訪問和測(cè)試
啟動(dòng)應(yīng)用后，訪問對(duì)應(yīng)的 Swagger UI 或 Knife4j 地址（如 http://localhost:8080/swagger-ui.html 或 http://localhost:8080/doc.html），即可查看并測(cè)試 API。
六、總結(jié)
本文介紹了在 Spring Boot 2 和 Spring Boot 3 中集成 Swagger 的實(shí)戰(zhàn)步驟：
- Spring Boot 2 使用 Springfox Swagger，配置簡(jiǎn)單但維護(hù)較少。
- Spring Boot 3 推薦 Springdoc OpenAPI，與新版本兼容且功能強(qiáng)大。
同時(shí)展示了多種接口文檔風(fēng)格：
- Swagger UI：交互性強(qiáng)，適合開發(fā)和調(diào)試。
- Redoc：簡(jiǎn)潔美觀，適合靜態(tài)文檔。
- Knife4j：功能豐富，體驗(yàn)更優(yōu)。
通過實(shí)戰(zhàn)示例，開發(fā)者可以快速上手并將 Swagger 應(yīng)用到自己的項(xiàng)目中，提升 API 管理的效率和質(zhì)量。
到此這篇關(guān)于SpringBoot+Swagger打造美觀API文檔的實(shí)戰(zhàn)指南的文章就介紹到這了,更多相關(guān)SpringBoot Swagger構(gòu)建API文檔內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
這篇文章主要介紹了Javaweb使用getPart接收表單文件過程解析,文中通過示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2020-07-07
微服務(wù)如何通過feign.RequestInterceptor傳遞參數(shù)
這篇文章主要介紹了微服務(wù)如何通過feign.RequestInterceptor傳遞參數(shù)，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2022-03-03
Spring中@EnableScheduling實(shí)現(xiàn)定時(shí)任務(wù)代碼實(shí)例
這篇文章主要介紹了Spring中@EnableScheduling實(shí)現(xiàn)定時(shí)任務(wù)代碼實(shí)例,@EnableScheduling 注解開啟定時(shí)任務(wù)功能,可以將多個(gè)方法寫在一個(gè)類,也可以分多個(gè)類寫,當(dāng)然也可以將方法直接寫在上面ScheddulConfig類中,需要的朋友可以參考下2024-01-01
java多線程數(shù)據(jù)分頁(yè)處理實(shí)例講解
在本篇內(nèi)容里小編給大家分享了一篇關(guān)于java多線程數(shù)據(jù)分頁(yè)處理實(shí)例講解內(nèi)容，有興趣的朋友們可以學(xué)習(xí)下。2021-01-01
在本篇文章中小編給大家整理了關(guān)于java8、jdk8日期轉(zhuǎn)化成字符串的相關(guān)知識(shí)點(diǎn)和代碼，需要的朋友們學(xué)習(xí)下。2019-04-04
jar包運(yùn)行時(shí)提示jar中沒有主清單屬性的解決
這篇文章主要介紹了jar包運(yùn)行時(shí)提示jar中沒有主清單屬性的解決方案，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2023-02-02
SpringBoot實(shí)現(xiàn)優(yōu)雅停機(jī)的正確方法
什么叫優(yōu)雅停機(jī)？就是向應(yīng)用進(jìn)程發(fā)出停止指令之后，能保證正在執(zhí)行的業(yè)務(wù)操作不受影響，直到操作運(yùn)行完畢之后再停止服務(wù)。本文就來和大家聊聊SpringBoot實(shí)現(xiàn)優(yōu)雅停機(jī)的正確姿勢(shì)，希望對(duì)大家有所幫助2023-01-01
JavaMail整合Spring實(shí)現(xiàn)郵件發(fā)送功能
這篇文章主要為大家詳細(xì)介紹了JavaMail整合Spring實(shí)現(xiàn)郵件發(fā)送功能，文中示例代碼介紹的非常詳細(xì)，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2022-08-08
postman?如何實(shí)現(xiàn)傳遞?ArrayList?給后臺(tái)
這篇文章主要介紹了postman?如何實(shí)現(xiàn)傳遞?ArrayList給后臺(tái)，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2021-12-12
Java高效實(shí)現(xiàn)excel轉(zhuǎn)pdf(支持帶圖片的轉(zhuǎn)換)
這篇文章主要為大家詳細(xì)介紹了如何用java實(shí)現(xiàn)excel轉(zhuǎn)pdf文件,并且支持excel單元格中帶有圖片的轉(zhuǎn)換,文中的示例代碼講解詳細(xì),需要的可以參考下2024-01-01