SpringBoot整合Swagger教程詳解
Spring Boot 是一個(gè)基于 Spring 框架的輕量級(jí)開源框架，它的出現(xiàn)極大地簡(jiǎn)化了 Spring 應(yīng)用的搭建和開發(fā)。在開發(fā)過程中，接口文檔是非常重要的一環(huán)，它不僅方便開發(fā)者查看和理解接口的功能和參數(shù)，還能幫助前后端開發(fā)協(xié)同工作，提高開發(fā)效率。本文將介紹如何在 Spring Boot 中使用 Swagger 來實(shí)現(xiàn)接口文檔的自動(dòng)生成。
一、關(guān)于 Swagger
Swagger 是一個(gè) RESTful 接口文檔的規(guī)范和工具集，它的目標(biāo)是統(tǒng)一 RESTful 接口文檔的格式和規(guī)范。在開發(fā)過程中，接口文檔是非常重要的一環(huán)，它不僅方便開發(fā)者查看和理解接口的功能和參數(shù)，還能幫助前后端開發(fā)協(xié)同工作，提高開發(fā)效率。在 Spring Boot 中，我們可以通過集成 Swagger 來實(shí)現(xiàn)接口文檔的自動(dòng)生成。Swagger 通過注解來描述接口，然后根據(jù)這些注解自動(dòng)生成接口文檔。
二、Swagger 的安裝
1、下載 Swagger
Swagger 的官方網(wǎng)站是 https://swagger.io/，我們可以在這里下載最新版本的 Swagger。
2、安裝 Swagger
安裝 Swagger 非常簡(jiǎn)單，只需要將下載的 Swagger 解壓到指定目錄即可。在解壓后的目錄中，我們可以找到 swagger-ui.html 頁面，這個(gè)頁面就是 Swagger 的 UI 界面。
三、Swagger 的使用
1、編寫接口
在編寫接口時(shí)，我們需要使用 Swagger 的注解來描述接口信息。常用的注解包括：
- @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 中，我們可以通過添加 Swagger 相關(guān)的依賴來啟用 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 中，我們還需要添加配置類來配置 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() 方法中，我們通過 `select() 方法配置掃描的包路徑，paths() 方法配置接口的訪問路徑，apiInfo() 方法配置接口文檔的相關(guān)信息。
3、查看接口文檔
啟動(dòng) Spring Boot 應(yīng)用后，我們可以在瀏覽器中訪問 http://localhost:8080/swagger-ui.html 來查看接口文檔。在 Swagger UI 頁面中，我們可以看到所有的接口信息，包括接口名稱、請(qǐng)求方式、請(qǐng)求路徑、請(qǐng)求參數(shù)、響應(yīng)參數(shù)等。
四、Swagger 的高級(jí)使用
1、描述數(shù)據(jù)模型
我們可以使用 @ApiModel 和 @ApiModelProperty 注解來描述數(shù)據(jù)模型和屬性。例如，我們可以編寫一個(gè) User 類，并在類上使用 @ApiModel 和
@ApiModelProperty 注解來描述該數(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 注解來描述枚舉類型。例如，我們可以編寫一個(gè) Gender 枚舉類型，并在枚舉值上使用 @ApiModelProperty 注解來描述該枚舉值：
@ApiModel(description = "性別") public enum Gender {
@ApiModelProperty(value = "男")
MALE,
@ApiModelProperty(value = "女")
FEMALE;
}
在上面的代碼中，@ApiModel 表示該枚舉類型是一個(gè)描述性別的枚舉類型，@ApiModelProperty 表示該枚舉值是描述男性的枚舉值或描述女性的枚舉值。
3、描述響應(yīng)參數(shù)
我們可以使用 @ApiResponses 和 @ApiResponse 注解來描述接口的響應(yīng)參數(shù)。例如，我們可以編寫一個(gè) getUserById() 方法，并在方法上使用 @ApiResponses 和 @ApiResponse 注解來描述該方法的響應(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() 方法來配置全局參數(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();
}
}
在上面的代碼中，我們通過 globalOperationParameters() 方法來配置一個(gè)全局的 Authorization 參數(shù)，用于授權(quán)。
2、配置安全協(xié)議
我們可以在配置類中使用 securitySchemes() 方法來配置安全協(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();
}
}
在上面的代碼中，我們通過 securitySchemes() 方法來配置一個(gè) Bearer Token 安全協(xié)議。
3、配置安全上下文
我們可以在配置類中使用 securityContexts() 方法來配置安全上下文。例如，我們可以配置一個(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();
}
}
在上面的代碼中，我們通過 securityContexts() 方法來配置一個(gè)安全上下文，用于在 Swagger UI 中顯示認(rèn)證按鈕。
4、配置忽略參數(shù)
在接口中，有些參數(shù)可能是敏感信息，我們不希望在接口文檔中顯示。我們可以使用 @ApiIgnore 注解來忽略這些參數(shù)。例如，我們可以在 User 類中使用 @ApiIgnore 注解來忽略密碼參數(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é)
通過集成 Swagger，我們可以方便地生成接口文檔，使得前后端開發(fā)協(xié)同更加高效。在使用 Swagger 時(shí)，我們需要注意以下幾點(diǎn)：
- 使用注解來描述接口信息，包括接口名稱、請(qǐng)求方式、請(qǐng)求路徑、請(qǐng)求參數(shù)、響應(yīng)參數(shù)等；
- 在配置類中配置 Swagger，包括掃描的包路徑、接口文檔信息、全局參數(shù)、安全協(xié)議、安全上下文等；
- 描述數(shù)據(jù)模型、枚舉類型、響應(yīng)參數(shù)等信息，方便開發(fā)者查看和理解接口的功能和參數(shù)；
- 在需要時(shí)使用 @ApiIgnore 注解來忽略敏感參數(shù)的顯示。
- 最后，需要注意的是，Swagger 只是一種規(guī)范和工具集，它并不能取代單元測(cè)試和集成測(cè)試等其他測(cè)試方式。在開發(fā)過程中，我們需要綜合使用各種測(cè)試方式，保證軟件的質(zhì)量和穩(wěn)定性。
以上就是SpringBoot整合Swagger教程詳解的詳細(xì)內(nèi)容，更多關(guān)于SpringBoot整合Swagger的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！
相關(guān)文章
SpringBoot入門編寫第一個(gè)程序Helloworld
這篇文章是Springboot入門篇，來教大家編寫第一個(gè)Springboot程序Helloworld，文中附有詳細(xì)的示例代碼，有需要的同學(xué)可以借鑒參考下2021-09-09
這篇文章主要介紹了Spring中@Value注解的使用方法詳解,在spring項(xiàng)目中必不可少的就是讀取配置文件,那么讀取配置文件就有兩種方式,一種就是使用Spring中@Value注解,還有一種是使用SpringBoot中的@ConfigurationProperties注解,需要的朋友可以參考下2024-01-01
這篇文章主要為大家詳細(xì)介紹了Java實(shí)現(xiàn)帶圖形界面的聊天程序，文中示例代碼介紹的非常詳細(xì)，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2022-06-06
詳解Kotlin和anko融合進(jìn)行Android開發(fā)
本篇文章主要介紹了Kotlin和anko融合進(jìn)行Android開發(fā)，小編覺得挺不錯(cuò)的，現(xiàn)在分享給大家，也給大家做個(gè)參考。一起跟隨小編過來看看吧2017-11-11
這篇文章主要為大家詳細(xì)介紹了Java仿Windows記事本源代碼，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2019-03-03
SpringCloud @RefreshScope注解源碼層面深入分析
@RefreshScope注解能幫助我們做局部的參數(shù)刷新，但侵入性較強(qiáng)，需要開發(fā)階段提前預(yù)知可能的刷新點(diǎn)，并且該注解底層是依賴于cglib進(jìn)行代理的，所以不要掉入cglib的坑，出現(xiàn)刷了也不更新情況2023-04-04
這篇文章主要介紹了SpringBoot資源文件的存放位置設(shè)置方式，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2021-11-11
本篇文章主要介紹了springboot中junit回滾，小編覺得挺不錯(cuò)的，現(xiàn)在分享給大家，也給大家做個(gè)參考。一起跟隨小編過來看看吧2017-10-10
本篇文章主要介紹了Spring Boot 使用Druid配置詳解，小編覺得挺不錯(cuò)的，現(xiàn)在分享給大家，也給大家做個(gè)參考。一起跟隨小編過來看看吧2017-05-05
Java模板方法模式是一種行為型設(shè)計(jì)模式，它定義了一個(gè)算法框架，由抽象父類定義算法的基本結(jié)構(gòu)，具體實(shí)現(xiàn)細(xì)節(jié)由子類來實(shí)現(xiàn)，從而實(shí)現(xiàn)代碼復(fù)用和擴(kuò)展性2023-05-05