SpringBoot整合Swagger教程詳解
Spring Boot 是一個(gè)基于 Spring 框架的輕量級(jí)開(kāi)源框架，它的出現(xiàn)極大地簡(jiǎn)化了 Spring 應(yīng)用的搭建和開(kāi)發(fā)。在開(kāi)發(fā)過(guò)程中，接口文檔是非常重要的一環(huán)，它不僅方便開(kāi)發(fā)者查看和理解接口的功能和參數(shù)，還能幫助前后端開(kāi)發(fā)協(xié)同工作，提高開(kāi)發(fā)效率。本文將介紹如何在 Spring Boot 中使用 Swagger 來(lái)實(shí)現(xiàn)接口文檔的自動(dòng)生成。
一、關(guān)于 Swagger
Swagger 是一個(gè) RESTful 接口文檔的規(guī)范和工具集，它的目標(biāo)是統(tǒng)一 RESTful 接口文檔的格式和規(guī)范。在開(kāi)發(fā)過(guò)程中，接口文檔是非常重要的一環(huán)，它不僅方便開(kāi)發(fā)者查看和理解接口的功能和參數(shù)，還能幫助前后端開(kāi)發(fā)協(xié)同工作，提高開(kāi)發(fā)效率。在 Spring Boot 中，我們可以通過(guò)集成 Swagger 來(lái)實(shí)現(xiàn)接口文檔的自動(dòng)生成。Swagger 通過(guò)注解來(lái)描述接口，然后根據(jù)這些注解自動(dòng)生成接口文檔。
二、Swagger 的安裝
1、下載 Swagger
Swagger 的官方網(wǎng)站是 https://swagger.io/，我們可以在這里下載最新版本的 Swagger。
2、安裝 Swagger
安裝 Swagger 非常簡(jiǎn)單，只需要將下載的 Swagger 解壓到指定目錄即可。在解壓后的目錄中，我們可以找到 swagger-ui.html 頁(yè)面，這個(gè)頁(yè)面就是 Swagger 的 UI 界面。
三、Swagger 的使用
1、編寫接口
在編寫接口時(shí)，我們需要使用 Swagger 的注解來(lái)描述接口信息。常用的注解包括：
- @Api：用于描述接口的類或接口
- @ApiOperation：用于描述接口的方法
- @ApiParam：用于描述接口的參數(shù)
- @ApiModel：用于描述數(shù)據(jù)模型
- @ApiModelProperty：用于描述數(shù)據(jù)模型的屬性
例如，我們編寫一個(gè)簡(jiǎn)單的接口：
@RestController
@Api(tags = "用戶接口")
public class UserController {
@GetMapping("/user/{id}")
@ApiOperation(value = "根據(jù) ID 獲取用戶信息")
public User getUserById(@ApiParam(value = "用戶 ID", required = true) @PathVariable Long id) {
// 根據(jù) ID 查詢用戶信息
}
}
在上面的代碼中，@Api表示該類是一個(gè)用戶接口，@ApiOperation 表示該方法是獲取用戶信息的接口，@ApiParam 表示該參數(shù)是用戶 ID，@PathVariable 表示該參數(shù)是路徑參數(shù)。
2、啟用 Swagger
在 Spring Boot 中，我們可以通過(guò)添加 Swagger 相關(guān)的依賴來(lái)啟用 Swagger。
我們可以在 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>
在 Spring Boot 中，我們還需要添加配置類來(lái)配置 Swagger。配置類的代碼如下：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文檔")
.description("接口文檔")
.version("1.0.0")
.build();
}
}
在上面的代碼中，@Configuration 表示該類是一個(gè)配置類，@EnableSwagger2 表示啟用 Swagger。在 api() 方法中，我們通過(guò) `select() 方法配置掃描的包路徑，paths() 方法配置接口的訪問(wèn)路徑，apiInfo() 方法配置接口文檔的相關(guān)信息。
3、查看接口文檔
啟動(dòng) Spring Boot 應(yīng)用后，我們可以在瀏覽器中訪問(wèn) http://localhost:8080/swagger-ui.html 來(lái)查看接口文檔。在 Swagger UI 頁(yè)面中，我們可以看到所有的接口信息，包括接口名稱、請(qǐng)求方式、請(qǐng)求路徑、請(qǐng)求參數(shù)、響應(yīng)參數(shù)等。
四、Swagger 的高級(jí)使用
1、描述數(shù)據(jù)模型
我們可以使用 @ApiModel 和 @ApiModelProperty 注解來(lái)描述數(shù)據(jù)模型和屬性。例如，我們可以編寫一個(gè) User 類，并在類上使用 @ApiModel 和
@ApiModelProperty 注解來(lái)描述該數(shù)據(jù)模型：
@ApiModel(description = "用戶信息")
public class User {
@ApiModelProperty(value = "用戶 ID", example ="1")
private Long id;
@ApiModelProperty(value = "用戶名", example = "張三")
private String username;
@ApiModelProperty(value = "密碼", example = "123456")
private String password;
// 省略 getter 和 setter 方法
}
在上面的代碼中，@ApiModel 表示該類是一個(gè)數(shù)據(jù)模型，@ApiModelProperty 表示該屬性是數(shù)據(jù)模型的一個(gè)屬性，value 屬性表示屬性的描述，example 屬性表示屬性的示例值。
2、描述枚舉類型
我們可以使用 @ApiModel 和 @ApiModelProperty 注解來(lái)描述枚舉類型。例如，我們可以編寫一個(gè) Gender 枚舉類型，并在枚舉值上使用 @ApiModelProperty 注解來(lái)描述該枚舉值：
@ApiModel(description = "性別") public enum Gender {
@ApiModelProperty(value = "男")
MALE,
@ApiModelProperty(value = "女")
FEMALE;
}
在上面的代碼中，@ApiModel 表示該枚舉類型是一個(gè)描述性別的枚舉類型，@ApiModelProperty 表示該枚舉值是描述男性的枚舉值或描述女性的枚舉值。
3、描述響應(yīng)參數(shù)
我們可以使用 @ApiResponses 和 @ApiResponse 注解來(lái)描述接口的響應(yīng)參數(shù)。例如，我們可以編寫一個(gè) getUserById() 方法，并在方法上使用 @ApiResponses 和 @ApiResponse 注解來(lái)描述該方法的響應(yīng)參數(shù)：
@GetMapping("/user/{id}")
@ApiOperation(value = "根據(jù) ID 獲取用戶信息")
@ApiResponses({ @ApiResponse(code = 200, message = "請(qǐng)求成功", response = User.class),
@ApiResponse(code = 404, message = "用戶不存在") })
public User getUserById(@ApiParam(value = "用戶 ID", required = true) @PathVariable Long id)
{
// 根據(jù) ID 查詢用戶信息
}
在上面的代碼中，@ApiResponses 表示該方法的響應(yīng)參數(shù)，@ApiResponse 表示該響應(yīng)參數(shù)的描述，code 屬性表示響應(yīng)碼，message 屬性表示響應(yīng)消息，response 屬性表示響應(yīng)的數(shù)據(jù)模型。
五、Swagger 的進(jìn)階使用
1、配置全局參數(shù)
我們可以在配置類中使用 globalOperationParameters() 方法來(lái)配置全局參數(shù)。例如，我們可以配置一個(gè)全局的 Authorization 參數(shù)，用于授權(quán)：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build()
.globalOperationParameters(Arrays.asList(
new ParameterBuilder()
.name("Authorization")
.description("授權(quán)")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false)
.build()
))
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文檔")
.description("接口文檔")
.version("1.0.0")
.build();
}
}
在上面的代碼中，我們通過(guò) globalOperationParameters() 方法來(lái)配置一個(gè)全局的 Authorization 參數(shù)，用于授權(quán)。
2、配置安全協(xié)議
我們可以在配置類中使用 securitySchemes() 方法來(lái)配置安全協(xié)議。例如，我們可以配置一個(gè) Bearer Token 安全協(xié)議：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build()
.securitySchemes(Arrays.asList(
new ApiKey("Bearer", "Authorization", "header")
))
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文檔")
.description("接口文檔")
.version("1.0.0")
.build();
}
}
在上面的代碼中，我們通過(guò) securitySchemes() 方法來(lái)配置一個(gè) Bearer Token 安全協(xié)議。
3、配置安全上下文
我們可以在配置類中使用 securityContexts() 方法來(lái)配置安全上下文。例如，我們可以配置一個(gè)安全上下文，用于在 Swagger UI 中顯示認(rèn)證按鈕：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build()
.securitySchemes(Arrays.asList(
new ApiKey("Bearer", "Authorization", "header")
))
.securityContexts(Collections.singletonList(
SecurityContext.builder()
.securityReferences(Collections.singletonList(
new SecurityReference("Bearer", new AuthorizationScope[0])
))
.build()
))
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文檔")
.description("接口文檔")
.version("1.0.0")
.build();
}
}
在上面的代碼中，我們通過(guò) securityContexts() 方法來(lái)配置一個(gè)安全上下文，用于在 Swagger UI 中顯示認(rèn)證按鈕。
4、配置忽略參數(shù)
在接口中，有些參數(shù)可能是敏感信息，我們不希望在接口文檔中顯示。我們可以使用 @ApiIgnore 注解來(lái)忽略這些參數(shù)。例如，我們可以在 User 類中使用 @ApiIgnore 注解來(lái)忽略密碼參數(shù)：
@ApiModel(description = "用戶信息")
public class User {
@ApiModelProperty(value = "用戶 ID", example = "1")
private Long id;
@ApiModelProperty(value = "用戶名", example = "張三")
private String username;
@ApiModelProperty(hidden = true)
@ApiIgnore
private String password;
// 省略 getter 和 setter 方法
}
在上面的代碼中，@ApiModelProperty(hidden = true) 表示該參數(shù)是隱藏的，@ApiIgnore 表示忽略該參數(shù)。
六、總結(jié)
通過(guò)集成 Swagger，我們可以方便地生成接口文檔，使得前后端開(kāi)發(fā)協(xié)同更加高效。在使用 Swagger 時(shí)，我們需要注意以下幾點(diǎn)：
- 使用注解來(lái)描述接口信息，包括接口名稱、請(qǐng)求方式、請(qǐng)求路徑、請(qǐng)求參數(shù)、響應(yīng)參數(shù)等；
- 在配置類中配置 Swagger，包括掃描的包路徑、接口文檔信息、全局參數(shù)、安全協(xié)議、安全上下文等；
- 描述數(shù)據(jù)模型、枚舉類型、響應(yīng)參數(shù)等信息，方便開(kāi)發(fā)者查看和理解接口的功能和參數(shù)；
- 在需要時(shí)使用 @ApiIgnore 注解來(lái)忽略敏感參數(shù)的顯示。
- 最后，需要注意的是，Swagger 只是一種規(guī)范和工具集，它并不能取代單元測(cè)試和集成測(cè)試等其他測(cè)試方式。在開(kāi)發(fā)過(guò)程中，我們需要綜合使用各種測(cè)試方式，保證軟件的質(zhì)量和穩(wěn)定性。
以上就是SpringBoot整合Swagger教程詳解的詳細(xì)內(nèi)容，更多關(guān)于SpringBoot整合Swagger的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！
- Springboot整合Swagger3全注解配置(springdoc-openapi-ui)
- SpringBoot整合Swagger3生成接口文檔過(guò)程解析
- Springboot整合Swagger2后訪問(wèn)swagger-ui.html 404報(bào)錯(cuò)問(wèn)題解決方案
- SpringBoot整合Swagger3生成接口文檔的示例代碼
- Springboot整合Swagger2和Swagger3全過(guò)程
- springboot整合swagger3和knife4j的詳細(xì)過(guò)程
- SpringBoot整合Swagger的方法示例
- SpringBoot整合swagger的操作指南
- SpringBoot整合Swagger接口文檔工具的流程步驟
- SpringBoot3.x整合swagger的實(shí)現(xiàn)示例
相關(guān)文章
Mybatis注解開(kāi)發(fā)@Select執(zhí)行參數(shù)和執(zhí)行sql語(yǔ)句的方式(最新詳解)
@Select 是 Mybatis 框架中的一個(gè)注解，用于執(zhí)行 SQL 查詢語(yǔ)句，并把查詢結(jié)果映射到指定的 Java 對(duì)象中，這篇文章主要介紹了Mybatis注解開(kāi)發(fā)@Select執(zhí)行參數(shù)和執(zhí)行sql語(yǔ)句的方式,需要的朋友可以參考下2023-07-07
MyBatis攔截器:給參數(shù)對(duì)象屬性賦值的實(shí)例
下面小編就為大家?guī)?lái)一篇MyBatis攔截器:給參數(shù)對(duì)象屬性賦值的實(shí)例。小編覺(jué)得挺不錯(cuò)的，現(xiàn)在就分享給大家，也給大家做個(gè)參考。一起跟隨小編過(guò)來(lái)看看吧2017-04-04
因?yàn)镾tring字符串很常用，所以我們?cè)谑褂盟倪^(guò)程中，可能會(huì)面臨各種問(wèn)題，比如”中文亂碼“問(wèn)題等，那么為什么中文會(huì)亂碼？本文將給大家介紹一下Java如何設(shè)置String字符串編碼，來(lái)避免和解決這一常見(jiàn)問(wèn)題,需要的朋友可以參考下2023-05-05
這篇文章主要介紹了公共POI導(dǎo)出Excel方法，文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧2019-05-05
SpringBoot開(kāi)發(fā)實(shí)戰(zhàn)系列之定時(shí)器
定時(shí)任務(wù)我想諸位童鞋都不陌生,簡(jiǎn)而言之名為“設(shè)定定時(shí)鬧鐘做某件事情”,下面這篇文章主要給大家介紹了關(guān)于SpringBoot定時(shí)器的相關(guān)資料,需要的朋友可以參考下2021-08-08
Spring Boot spring-boot-maven-plugin 參數(shù)配置詳解(最
文章介紹了Spring Boot Maven插件的5個(gè)核心目標(biāo)（repackage、run、start、stop、build-info）及其應(yīng)用場(chǎng)景,涵蓋應(yīng)用打包、運(yùn)行、集成測(cè)試、構(gòu)建信息生成、依賴管理等,同時(shí)說(shuō)明了如何配置pom.xml、調(diào)試參數(shù)及隨機(jī)端口設(shè)置,感興趣的朋友一起看看吧2025-07-07
SpringBoot+WebSocket實(shí)現(xiàn)IM及時(shí)通訊的代碼示例
項(xiàng)目中碰到需要及時(shí)通訊的場(chǎng)景,使用springboot集成websocket,即可實(shí)現(xiàn)簡(jiǎn)單的及時(shí)通訊,本文介紹springboot如何集成websocket、IM及時(shí)通訊需要哪些模塊、開(kāi)發(fā)和部署過(guò)程中遇到的問(wèn)題、以及實(shí)現(xiàn)小型IM及時(shí)通訊的代碼,需要的朋友可以參考下2023-10-10
關(guān)于kafka發(fā)送消息的三種方式總結(jié)
這篇文章主要介紹了關(guān)于kafka發(fā)送消息的三種方式總結(jié)，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2023-04-04
詳解SpringBoot獲得Maven-pom中版本號(hào)和編譯時(shí)間戳
這篇文章主要介紹了詳解SpringBoot獲得Maven-pom中版本號(hào)和編譯時(shí)間戳，文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧2020-01-01
這篇文章主要介紹了JAVA Actor模型的的相關(guān)資料，文中講解非常細(xì)致，幫助大家更好的學(xué)習(xí)JAVA，感興趣的朋友可以了解下2020-06-06