SpringBoot整合Swagger教程詳解

更新時間：2023年04月14日 10:47:37 作者：Java?Fans

SpringBoot是一個基于Spring框架的輕量級開源框架，它的出現(xiàn)極大地簡化了Spring應(yīng)用的搭建和開發(fā)，本文將介紹如何在SpringBoot中使用Swagger來實現(xiàn)接口文檔的自動生成，感興趣的同學(xué)可以參考一下

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ī)范和工具集，它的目標是統(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)定性。

以上就是SpringBoot整合Swagger教程詳解的詳細內(nèi)容，更多關(guān)于SpringBoot整合Swagger的資料請關(guān)注腳本之家其它相關(guān)文章！

您可能感興趣的文章:

欧美bbbwbbbw肥妇,免费乱码人妻系列日韩,一级黄片

SpringBoot整合Swagger教程詳解

目錄

一、關(guān)于 Swagger

二、Swagger 的安裝

1、下載 Swagger

2、安裝 Swagger

三、Swagger 的使用

1、編寫接口

2、啟用 Swagger

3、查看接口文檔

四、Swagger 的高級使用

1、描述數(shù)據(jù)模型

2、描述枚舉類型

3、描述響應(yīng)參數(shù)

五、Swagger 的進階使用

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

2、配置安全協(xié)議

3、配置安全上下文

4、配置忽略參數(shù)

六、總結(jié)

相關(guān)文章

最新評論

大家感興趣的內(nèi)容

最近更新的內(nèi)容

常用在線小工具

欧美bbbwbbbw肥妇,免费乱码人妻系列日韩,一级黄片

SpringBoot整合Swagger教程詳解

目錄

一、關(guān)于 Swagger

二、Swagger 的安裝

1、下載 Swagger

2、安裝 Swagger

三、Swagger 的使用

1、編寫接口

2、啟用 Swagger

3、查看接口文檔

四、Swagger 的高級使用

1、描述數(shù)據(jù)模型

2、描述枚舉類型

3、描述響應(yīng)參數(shù)

五、Swagger 的進階使用

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

2、配置安全協(xié)議

3、配置安全上下文

4、配置忽略參數(shù)

六、總結(jié)

相關(guān)文章

最新評論

大家感興趣的內(nèi)容

最近更新的內(nèi)容

常用在線小工具

一、關(guān)于 Swagger

二、Swagger 的安裝

1、下載 Swagger

2、安裝 Swagger

三、Swagger 的使用

1、編寫接口

2、啟用 Swagger

3、查看接口文檔

四、Swagger 的高級使用

1、描述數(shù)據(jù)模型

五、Swagger 的進階使用

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

3、配置安全上下文