SpringBoot整合Swagger教程详解

2023-04-12 10:25 开发作者： Java Fans

Spring Boot 是一个基于 Spring 框架的轻量级开源框架，它的出现极大地简化了 Spring 应用的搭建和开发。在开发过程中，接口文档是非常重要的一环，它不仅方便开发者查看和理解接口的功能和参数，还能帮助前后端开发协同工作，提高开发效率。本文将介绍如何在 Spring Boot 中使用 Swagger 来实现接口文档的自动生成。

一、关于 Swagger

Swagger 是一个 RESTful 接口文档的规范和工具集，它的目标是统一 RESTful 接口文档的格式和规范。在开发过程中，接口文档是非常重要的一环，它不仅方便开发者查看和理解接口的功能和参数，还能帮助前后端开发协同工作，提高开发效率。在 Spring Boot 中，我们可以通过集成 Swagger 来实现接口文档的自动生成。Swagger 通过注解来描述接口，然后根据这些注解自动生成接口文档。

二、Swagger 的安装

1、下载 Swagger

Swagger 的官方网站是 https://swagger.io/，我们可以在这里下载最新版本的 Swagger。

2、安装 Swagger

安装 Swagger 非常简单，只需要将下载的 Swagger 解压到指定目录即可。在解压后的目录中，我们可以找到 swagger-ui.html 页面，这个页面就是 Swagger 的 UI 界面。

三、Swagger 的使用

1、编写接口

在编写接口时，我们需要使用 Swagger 的注解来描述接口信息。常用的注解包括：

@Api：用于描述接口的类或接口
@ApiOperation：用于描述接口的方法
@ApiParam：用于描述接口的参数
@ApiModel：用于描述数据模型
@ApiModelProperty：用于描述数据模型的属性

例如，我们编写一个简单的接口：

@RestController
@Api(tags = "用户接口")
public class UserController {
 
    @GetMapping("/user/{id}")
    @ApiOperation(value = "根据 ID 获取用户信息")
    public User getUserById(@ApiParam(value = "用户 ID", required = true) @PathVariable Long id) {
        // 根据 ID 查询用户信息
    }
}

在上面的代码中，@Api表示该类是一个用户接口，@ApiOperation 表示该方法是获取用户信息的接口，@ApiParam 表示该参数是用户 ID，@PathVariable 表示该参数是路径参数。

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.basePackajavascriptge("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 页面中，我们可以看到所有的接口信息，包括接口名称、请求方式、请求路径、请求参数、响应参数等。

四、Swagger 的高级使用

1、描述数据模型

我们可以使用 @ApiModel 和 @ApiModelProperty 注解来描述数据模型和属性。例如，我们可以编写一个 User 类，并在类上使用 @ApiModel 和

@ApiModelProperty 注解来描述该数据模型：

@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 表示该类是一个数据模型，@ApiModelProperty 表示该属性是数据模型的一个属性，value 属性表示属性的描述，example 属性表示属性的示例值。

2、描述枚举类型

我们可以使用 @ApiModel 和 @ApiModelProperty 注解来描述枚举类型。例如，我们可以编写一个 Gender 枚举类型，并在枚举值上使用 @ApiModelProperty 注解来描述该枚举值：

@ApiModel(description开发者_Go学习 = "性别") public enum Gender {

@ApiModelProperty(value = "男")
MALE,

@ApiModelProperty(value = "女")
FEMALE;
}

在上面的代码中，@ApiModel 表示该枚举类型是一个描述性别的枚举类型，@ApiModelProperty 表示该枚举值是描述男性的枚举值或描述女性的枚举值。

3、描述响应参数

我们可以使用 @ApiResponses 和 @ApiResponse 注解来描述接口的响应参数。例如，我们可以编写一个 getUserById() 方法，并在方法上使用 @ApiResponses 和 @ApiResponse 注解来描述该方法的响应参数：

@GetMapping("/user/{id}")
@ApiOperation(value = "根据 ID 获取用户信息") 
@ApiResponses({ @ApiResponse(code = 200, message = "请求成功", response = User.class), 
@ApiResponse(code = 404, message = "用户不存在") }) 
public User getUserById(@ApiParam(value = "用户 ID", required = true) @PathVariable Long id) 
{ 
	// 根据 ID javascript查询用户信息 
}

在上面的代码中，@ApiResponses 表示该方法的响应参数，@ApiResponse 表示该响应参数的描述，code 属性表示响应码，message 属性表示响应消息，response 属性表示响应的数据模型。

五、Swagger 的进阶使用

1、配置全局参数

我们可以在配置类中使用 globalOperationParameters() 方法来配置全局参数。例如，我们可以配置一个全局的 Authorization 参数，用于授权：

@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"))
              php                  .parameterType("header")
                              php  .required(false)
                                .build()
                ))
                .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("接口文档")
                .version("1.0.0")
                .build();
    }
 
}

在上面的代码中，我们通过 globalOperationParameters() 方法来配置一个全局的 Authorization 参数，用于授权。

2、配置安全协议

我们可以在配置类中使用 securitySchemes() 方法来配置安全协议。例如，我们可以配置一个 Bearer Token 安全协议：

@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 安全协议。

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、配置忽略参数

在接口中，有些参数可能是敏感信息，我们不希望在接口文档中显示。我们可以使用 @ApiIgnore 注解来忽略这些参数。例如，我们可以在 User 类中使用 @ApiIgnore 注解来忽略密码参数：

@ApiModel(description = "用户信息")
public class User {
 
    @ApiModelProperty(value = "用户 ID", example = "1")
    private Long id;
 
    @ApiModelProperty(value = "用户名", example = "张三www.devze.com")
    private String username;
 
    @ApiModelProperty(hidden = true)
    @ApiIgnore
    private String password;
 
    // 省略 getter 和 setter 方法
}

在上面的代码中，@ApiModelProperty(hidden = true) 表示该参数是隐藏的，@ApiIgnore 表示忽略该参数。

六、总结

通过集成 Swagger，我们可以方便地生成接口文档，使得前后端开发协同更加高效。在使用 Swagger 时，我们需要注意以下几点：

使用注解来描述接口信息，包括接口名称、请求方式、请求路径、请求参数、响应参数等；
在配置类中配置 Swagger，包括扫描的包路径、接口文档信息、全局参数、安全协议、安全上下文等；
描述数据模型、枚举类型、响应参数等信息，方便开发者查看和理解接口的功能和参数；
在需要时使用 @ApiIgnore 注解来忽略敏感参数的显示。
最后，需要注意的是，Swagger 只是一种规范和工具集，它并不能取代单元测试和集成测试等其他测试方式。在开发过程中，我们需要综合使用各种测试方式，保证软件的质量和稳定性。

以上就是SpringBoot整合Swagger教程详解的详细内容，更多关于SpringBoot整合Swagger的资料请关注我们其它相关文章！

继续阅读：SpringBoot整合Swagger

SpringBoot整合Swagger教程详解

目录

一、关于 Swagger

二、Swagger 的安装

1、下载 Swagger

2、安装 Swagger

三、Swagger 的使用

1、编写接口

2、启用 Swagger

3、查看接口文档

四、Swagger 的高级使用

1、描述数据模型

2、描述枚举类型

3、描述响应参数

五、Swagger 的进阶使用

1、配置全局参数

2、配置安全协议

3、配置安全上下文

4、配置忽略参数

六、总结

更多精彩内容

精彩评论

最新开发

使用Spring Security和JWT实现安全认证机制

Go中的Context实现原理以及正确使用方式

C# wpf常用窗口特效的实现代码

十大C#中最具价值的语法糖分享

C#中openFileDialog控件的使用方法

开发排行榜

springboot后端存储富文本内容的思路与步骤(含图片内容)

PyCharm运行python测试,报错“没有发现测试”/“空套件”的解决

return base64.b64encode(b).decode(

基于C语言实现钻石棋游戏的示例代码

Sublime Text 3解决中文乱码问题（实测可用）