SpringBoot整合Swagger的方法是什么

本文小編為大家詳細介紹“SpringBoot整合Swagger的方法是什么”，內(nèi)容詳細，步驟清晰，細節(jié)處理妥當，希望這篇“SpringBoot整合Swagger的方法是什么”文章能幫助大家解決疑惑，下面跟著小編的思路慢慢深入，一起來學習新知識吧。

Spring Boot 是一個基于 Spring 框架的輕量級開源框架，它的出現(xiàn)極大地簡化了 Spring 應用的搭建和開發(fā)。在開發(fā)過程中，接口文檔是非常重要的一環(huán)，它不僅方便開發(fā)者查看和理解接口的功能和參數(shù)，還能幫助前后端開發(fā)協(xié)同工作，提高開發(fā)效率。

一、關于 Swagger

Swagger 是一個 RESTful 接口文檔的規(guī)范和工具集，它的目標是統(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 相關的依賴來啟用 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() 方法配置接口文檔的相關信息。

3、查看接口文檔

啟動 Spring Boot 應用后，我們可以在瀏覽器中訪問 http://localhost:8080/swagger-ui.html 來查看接口文檔。在 Swagger UI 頁面中，我們可以看到所有的接口信息，包括接口名稱、請求方式、請求路徑、請求參數(shù)、響應參數(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、描述響應參數(shù)

我們可以使用 @ApiResponses 和 @ApiResponse 注解來描述接口的響應參數(shù)。例如，我們可以編寫一個 getUserById() 方法，并在方法上使用 @ApiResponses 和 @ApiResponse 注解來描述該方法的響應參數(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 表示該方法的響應參數(shù)，@ApiResponse 表示該響應參數(shù)的描述，code 屬性表示響應碼，message 屬性表示響應消息，response 屬性表示響應的數(shù)據(jù)模型。

五、Swagger 的進階使用

1、配置全局參數(shù)

我們可以在配置類中使用 globalOperationParameters() 方法來配置全局參數(shù)。例如，我們可以配置一個全局的 Authorization 參數(shù)，用于授權：

@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("授權")
                                .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ù)，用于授權。

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ù)。

讀到這里，這篇“SpringBoot整合Swagger的方法是什么”文章已經(jīng)介紹完畢，想要掌握這篇文章的知識點還需要大家自己動手實踐使用過才能領會，如果想了解更多相關內(nèi)容的文章，歡迎關注億速云行業(yè)資訊頻道。