?作者簡介：2022年博客新星 第八。熱愛國學(xué)的Java后端開發(fā)者，修心和技術(shù)同步精進。
??個人主頁：Java Fans的博客
??個人信條：不遷怒，不貳過。小知識，大智慧。
??當(dāng)前專欄：SpringBoot 框架從入門到精通
?特色專欄：國學(xué)周更-心性養(yǎng)成之路
??本文內(nèi)容：Spring Boot 整合 Swagger 教程詳解
??Spring Boot 是一個基于 Spring 框架的輕量級開源框架，它的出現(xiàn)極大地簡化了 Spring 應(yīng)用的搭建和開發(fā)。在開發(fā)過程中，接口文檔是非常重要的一環(huán)，它不僅方便開發(fā)者查看和理解接口的功能和參數(shù)，還能幫助前后端開發(fā)協(xié)同工作，提高開發(fā)效率。本文將介紹如何在 Spring Boot 中使用 Swagger 來實現(xiàn)接口文檔的自動生成。
一、關(guān)于 Swagger
??Swagger 是一個 RESTful 接口文檔的規(guī)范和工具集，它的目標(biāo)是統(tǒng)一 RESTful 接口文檔的格式和規(guī)范。在開發(fā)過程中，接口文檔是非常重要的一環(huán)，它不僅方便開發(fā)者查看和理解接口的功能和參數(shù)，還能幫助前后端開發(fā)協(xié)同工作，提高開發(fā)效率。在 Spring Boot 中，我們可以通過集成 Swagger 來實現(xiàn)接口文檔的自動生成。Swagger 通過注解來描述接口，然后根據(jù)這些注解自動生成接口文檔。
二、Swagger 的安裝
1、下載 Swagger
??Swagger 的官方網(wǎng)站是 https://swagger.io/，我們可以在這里下載最新版本的 Swagger。
2、安裝 Swagger
??安裝 Swagger 非常簡單，只需要將下載的 Swagger 解壓到指定目錄即可。在解壓后的目錄中，我們可以找到 swagger-ui.html 頁面，這個頁面就是 Swagger 的 UI 界面。
三、Swagger 的使用
1、編寫接口
??在編寫接口時，我們需要使用 Swagger 的注解來描述接口信息。常用的注解包括：
@Api：用于描述接口的類或接口@ApiOperation：用于描述接口的方法@ApiParam：用于描述接口的參數(shù)@ApiModel：用于描述數(shù)據(jù)模型@ApiModelProperty：用于描述數(shù)據(jù)模型的屬性
??例如，我們編寫一個簡單的接口：
@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表示該類是一個用戶接口，@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 表示該類是一個配置類，@EnableSwagger2 表示啟用 Swagger。在 api() 方法中，我們通過 `select() 方法配置掃描的包路徑，paths() 方法配置接口的訪問路徑，apiInfo() 方法配置接口文檔的相關(guān)信息。
3、查看接口文檔
??啟動 Spring Boot 應(yīng)用后，我們可以在瀏覽器中訪問 http://localhost:8080/swagger-ui.html 來查看接口文檔。在 Swagger UI 頁面中，我們可以看到所有的接口信息，包括接口名稱、請求方式、請求路徑、請求參數(shù)、響應(yīng)參數(shù)等。
四、Swagger 的高級使用
1、描述數(shù)據(jù)模型
??我們可以使用 @ApiModel 和 @ApiModelProperty 注解來描述數(shù)據(jù)模型和屬性。例如，我們可以編寫一個 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 表示該類是一個數(shù)據(jù)模型，@ApiModelProperty 表示該屬性是數(shù)據(jù)模型的一個屬性，value 屬性表示屬性的描述，example 屬性表示屬性的示例值。
2、描述枚舉類型
??我們可以使用 @ApiModel 和 @ApiModelProperty 注解來描述枚舉類型。例如，我們可以編寫一個 Gender 枚舉類型，并在枚舉值上使用 @ApiModelProperty 注解來描述該枚舉值：
@ApiModel(description = "性別") public enum Gender {
@ApiModelProperty(value = "男")
MALE,
@ApiModelProperty(value = "女")
FEMALE;
}
??在上面的代碼中，@ApiModel 表示該枚舉類型是一個描述性別的枚舉類型，@ApiModelProperty 表示該枚舉值是描述男性的枚舉值或描述女性的枚舉值。
3、描述響應(yīng)參數(shù)
??我們可以使用 @ApiResponses 和 @ApiResponse 注解來描述接口的響應(yīng)參數(shù)。例如，我們可以編寫一個 getUserById() 方法，并在方法上使用 @ApiResponses 和 @ApiResponse 注解來描述該方法的響應(yīng)參數(shù)：
@GetMapping("/user/{id}")
@ApiOperation(value = "根據(jù) ID 獲取用戶信息")
@ApiResponses({ @ApiResponse(code = 200, message = "請求成功", 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 的進階使用
1、配置全局參數(shù)
??我們可以在配置類中使用 globalOperationParameters() 方法來配置全局參數(shù)。例如，我們可以配置一個全局的 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() 方法來配置一個全局的 Authorization 參數(shù)，用于授權(quán)。
2、配置安全協(xié)議
??我們可以在配置類中使用 securitySchemes() 方法來配置安全協(xié)議。例如，我們可以配置一個 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() 方法來配置一個 Bearer Token 安全協(xié)議。
3、配置安全上下文
??我們可以在配置類中使用 securityContexts() 方法來配置安全上下文。例如，我們可以配置一個安全上下文，用于在 Swagger UI 中顯示認證按鈕：
@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() 方法來配置一個安全上下文，用于在 Swagger UI 中顯示認證按鈕。
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ù)、響應(yīng)參數(shù)等；在配置類中配置 Swagger，包括掃描的包路徑、接口文檔信息、全局參數(shù)、安全協(xié)議、安全上下文等；描述數(shù)據(jù)模型、枚舉類型、響應(yīng)參數(shù)等信息，方便開發(fā)者查看和理解接口的功能和參數(shù)；- 在需要時使用
@ApiIgnore 注解來忽略敏感參數(shù)的顯示。 - 最后，需要注意的是，
Swagger 只是一種規(guī)范和工具集，它并不能取代單元測試和集成測試等其他測試方式。在開發(fā)過程中，我們需要綜合使用各種測試方式，保證軟件的質(zhì)量和穩(wěn)定性。
??碼文不易，本篇文章就介紹到這里，如果想要學(xué)習(xí)更多Java系列知識，點擊關(guān)注博主，博主帶你零基礎(chǔ)學(xué)習(xí)Java知識。與此同時，對于日常生活有困擾的朋友，歡迎閱讀我的第四欄目：《國學(xué)周更—心性養(yǎng)成之路》，學(xué)習(xí)技術(shù)的同時，我們也注重了心性的養(yǎng)成。文章來源：http://www.zghlxwxcb.cn/news/detail-413409.html
文章來源地址http://www.zghlxwxcb.cn/news/detail-413409.html
到了這里，關(guān)于Spring Boot 整合 Swagger 教程詳解的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
