SpringBoot+Swagger打造美觀API文檔的實戰(zhàn)指南
導語
在現(xiàn)代 Web 開發(fā)中，API 文檔是開發(fā)者和團隊協(xié)作的重要組成部分。Swagger 作為一款強大的 API 文檔生成工具，能夠自動生成直觀、可交互的接口文檔，提升開發(fā)效率。本文將詳細介紹如何在 Spring Boot 2 和 Spring Boot 3 中集成 Swagger，并展示多種接口文檔風格，幫助開發(fā)者選擇適合自己項目的展示方式。
一、Swagger 簡介
Swagger 是一個開源工具，用于生成、描述和可視化 RESTful API。它不僅能自動生成 API 文檔，還提供交互式界面，方便開發(fā)者測試和調(diào)試接口。Swagger 與 Spring Boot 集成后，可以輕松管理和展示項目的 API。
二、Spring Boot 2 集成 Swagger
Spring Boot 2 中，常用的 Swagger 集成方案是基于 Springfox 庫。以下是具體步驟：
1. 添加依賴
在項目的 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)建一個配置類，例如 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
啟動 Spring Boot 應用后，打開瀏覽器訪問 http://localhost:8080/swagger-ui.html，即可看到生成的 API 文檔界面。
三、Spring Boot 3 集成 Swagger
Spring Boot 3 中，由于 Springfox 已不再積極維護，推薦使用 Springdoc OpenAPI 庫。它與 Spring Boot 3 的新特性（如 Jakarta EE）兼容，且配置更簡單。
1. 添加依賴
在 pom.xml 中添加 Springdoc OpenAPI 的依賴：
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.9</version>
</dependency>
2. 配置 Swagger
Springdoc 默認自動啟用 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
啟動應用后，訪問 http://localhost:8080/swagger-ui.html，即可查看 API 文檔。
四、多種接口文檔風格展示
Swagger 提供了多種 UI 風格，開發(fā)者可以根據(jù)需求選擇合適的展示方式。以下是幾種常見的風格及其配置方法：
1. 默認 Swagger UI
Swagger UI 是最常用的風格，提供交互式界面，支持 API 測試。Spring Boot 2 和 3 默認集成后即可使用：
- Spring Boot 2：
http://localhost:8080/swagger-ui.html - Spring Boot 3：
http://localhost:8080/swagger-ui.html
2. Redoc
Redoc 是一個簡潔、美觀的靜態(tài)文檔展示工具，適合生成靜態(tài) API 文檔。在 Spring Boot 3 中使用 Springdoc 配置：
在 application.properties 中添加：
# 禁用默認 Swagger UI springdoc.swagger-ui.enabled=false # 啟用 Redoc springdoc.redoc.enabled=true
訪問 http://localhost:8080/redoc，即可查看 Redoc 風格的文檔。
3. Knife4j
Knife4j 是 Swagger 的增強版，提供更豐富的功能和更友好的界面，支持 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，即可體驗 Knife4j 界面。
在 Spring Boot 3 中集成 Knife4j
添加依賴：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
無需額外配置，啟動應用后訪問 http://localhost:8080/doc.html。
五、實戰(zhàn)示例
以下是一個簡單的 Spring Boot 項目示例，展示如何使用 Swagger 注解生成詳細的 API 文檔。
1. 創(chuàng)建控制器
創(chuàng)建一個簡單的 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 注解
為控制器和方法添加注解，提供更詳細的 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. 訪問和測試
啟動應用后，訪問對應的 Swagger UI 或 Knife4j 地址（如 http://localhost:8080/swagger-ui.html 或 http://localhost:8080/doc.html），即可查看并測試 API。
六、總結(jié)
本文介紹了在 Spring Boot 2 和 Spring Boot 3 中集成 Swagger 的實戰(zhàn)步驟：
- Spring Boot 2 使用 Springfox Swagger，配置簡單但維護較少。
- Spring Boot 3 推薦 Springdoc OpenAPI，與新版本兼容且功能強大。
同時展示了多種接口文檔風格：
- Swagger UI：交互性強，適合開發(fā)和調(diào)試。
- Redoc：簡潔美觀，適合靜態(tài)文檔。
- Knife4j：功能豐富，體驗更優(yōu)。
通過實戰(zhàn)示例，開發(fā)者可以快速上手并將 Swagger 應用到自己的項目中，提升 API 管理的效率和質(zhì)量。
到此這篇關于SpringBoot+Swagger打造美觀API文檔的實戰(zhàn)指南的文章就介紹到這了,更多相關SpringBoot Swagger構(gòu)建API文檔內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！
相關文章
Java的web開發(fā)中SSH框架的協(xié)作處理應用筆記
這篇文章主要介紹了Java的web開發(fā)中SSH框架的協(xié)作處理應用筆記,SSH是指Struts和Spring以及Hibernate的框架搭配,需要的朋友可以參考下2015-12-12
這篇文章主要介紹了Jenkins安裝和插件管理知識，本文通過圖文并茂的形式給大家介紹的非常詳細，對大家的學習或工作具有一定的參考借鑒價值,需要的朋友可以參考下2022-02-02
springboot整合shardingjdbc實現(xiàn)分庫分表最簡單demo
我們知道分庫分表是針對某些數(shù)據(jù)量持續(xù)大幅增長的表，比如用戶表、訂單表等，而不是一刀切將全部表都做分片，這篇文章主要介紹了springboot整合shardingjdbc實現(xiàn)分庫分表最簡單demo,需要的朋友可以參考下2021-06-06
這篇文章主要給大家介紹了關于Java中初始化List的5種方法，文中通過示例代碼介紹的非常詳細，對大家學習或使用java具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2018-11-11
springMVC利用FastJson接口返回json數(shù)據(jù)相關配置詳解
本篇文章主要介紹了springMVC利用FastJson接口返回json數(shù)據(jù)相關配置詳解，具有一定的參考價值，感興趣的小伙伴們可以參考一下2017-06-06
Spring實戰(zhàn)之Bean銷毀之前的行為操作示例
這篇文章主要介紹了Spring實戰(zhàn)之Bean銷毀之前的行為操作,結(jié)合實例形式分析了spring在bean銷毀之前的行為相關設置與使用技巧,需要的朋友可以參考下2019-11-11
這篇文章主要介紹了Java讀取圖片EXIF信息的方法,較為詳細的分析了圖片EXIF信息的概念、功能及java讀取EXIF信息的實現(xiàn)技巧,需要的朋友可以參考下2015-07-07
Spring源碼BeanFactoryPostProcessor詳解
BeanFactoryPostProcessor的執(zhí)行時機是在Spring掃描完成后,Bean初始化前,當我們實現(xiàn)BeanFactoryPostProcessor接口,可以在Bean的初始化之前對Bean進行屬性的修改，下面通過本文看下Spring源碼分析-BeanFactoryPostProcessor的實例代碼，感興趣的朋友一起看看吧2021-11-11
這篇文章主要為大家介紹了java基于websocket實現(xiàn)im聊天功能示例詳解,有需要的朋友可以借鑒參考下,希望能夠有所幫助,祝大家多多進步,早日升職加薪2023-11-11
MyBatis?多表聯(lián)合查詢及優(yōu)化方法
大家都知道Hibernate 是全自動的數(shù)據(jù)庫持久層框架，它可以通過實體來映射數(shù)據(jù)庫，通過設置一對多、多對一、一對一、多對多的關聯(lián)來實現(xiàn)聯(lián)合查詢，接下來通過本文給大家介紹MyBatis?多表聯(lián)合查詢及優(yōu)化,需要的朋友可以參考下2022-08-08