Java：SpringBoot系列——第六章整合Swagger

Julissa.

已于 2023-01-12 13:05:46 修改

阅读量2k

点赞数 4

于 2023-01-12 13:04:55 首次发布

本文链接：https://blog.csdn.net/chenyouchang/article/details/128657359

版权

SpringBoot系列——第六章整合Swagger

前言

前后端分离开发，后端需要编写接口说明文档，接口文档其实是开发之前双方之间的一种约定。

通常接口文档分为离线的和实时的：

离线的接口文档需要程序员在上面编写，通常是由开发人员先在离线接口文档上编写信息，然后交给前端人员参照开发。最大的弊端是当我们的接口程序发生变动时，需要回过头来修改上面的内容。
实时接口文档就是可以根据我们的代码来自动生成相应的接口文档，优点就是我们的代码发生变化时，生成的接口文档也会自动更新，无需我们关注修改，只需要按时发布即可。

一、Swagger的介绍

1. Swagger的概述

swagger是一个用于生成服务器接口规范性文档，并且能够对接口进行测试的工具

swagger分为swagger2和swagger3两个常用版本。二者区别不是很大，主要对于依赖和注解进行了优化。swagger2需要引入2个jar包，swagger3只需要一个，用起来没有什么大的区别。

2. Swagger的作用

生成接口规范文档
对接口进行测试

二、SpringBoot集成Swagger

1. 添加依赖

在pom.xml添加依赖(swagger2、swagger-UI)

<!-- springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. 配置Swagger

创建swagger的配置类（Java配置方式）

在创建的类上添加

@Configuration声明为配置类

@EnableSwagger2声明在项目中开启了Swagger的功能

可以添加一个Docket配置。所谓Docket配置，就是一组(一个项目或一个版本)接口文档的配置，比如设置名称，联系人等等。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /*
    * 1.配置生成的文档信息
    * 2.配置生成规则
    * */

    //Docket封装接口文档信息
    @Bean
    public Docket getDocket(){

        //创建封面信息对象
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
        apiInfoBuilder.title("《商城项目》后端接口说明")
                .description("此文档详细说明了商城项目后端接口规范")
                .version("v 2.0.1")
                .contact(new Contact("小清","https://blog.csdn.net/chenyouchang","xiaoqing@qq.com"));
        ApiInfo apiInfo = apiInfoBuilder.build();

        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xiaoqing.xqmail.controllers"))
                .build();

        return docket;
    }
}

3. 启动项目

在这里插入图片描述

出现这个问题的主要原因确实是SpringBoot版本过高导致。Spring Boot 2.6.X使用PathPatternMatcher匹配路径，Swagger引用的Springfox使用的路径匹配是基于AntPathMatcher的。
如果是SpringBoot2.5.x及之前版本可以正常运行。

解决方法：

在springBoot配置文件中添加如下配置即可

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

4. 测试

访问地址：http://localhost:8080/swagger-ui.html出现下面界面则配置成功

在这里插入图片描述

测试接口方法：

在这里插入图片描述

测试成功

三、更改Swagger的界面风格

1. 添加依赖

在pom.xml中添加依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

2. 创建配置类

添加一个配置类，让他实现WebMvcConfigurer 接口

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
}

3. 测试

重启项目，访问http://localhost:8080/doc.html

在这里插入图片描述

风格更改成功，这种风格的界面也是用的比较多的。

四、Swagger注解

Swagger提供了一套注解，可以对每个接口进行详细的说明

1. @API

类注解，在控制器类添加此注解，可以对控制器类进行功能说明

@Api(value = "提供用户列表接口",tags = "用户管理")
@Api(value = "提供商品的添加，删除，列表功能接口...",tags = "商品管理")

在这里插入图片描述

2. @ApiOperation

方法注解，说明接口方法的作用

在这里插入图片描述

3. @ApiImplicitParams 和 @ApiImplicitParam

方法注解，说明接口方法的参数

@ApiOperation("用户登录接口")
@ApiImplicitParams({
        @ApiImplicitParam(dataType = "string",name = "username",value = "用户登录账号",required = true),
        @ApiImplicitParam(dataType = "string",name = "password",value = "用户登录密码",required = false,defaultValue = "123456")
})
@RequestMapping(value = "/login",method = RequestMethod.GET)
public ResultVo login(@RequestParam("username") String name,
                      @RequestParam(value = "password",defaultValue = "123456") String pwd){
    User user = userService.checkLogin(name, pwd);
    if(user == null){
        return new ResultVo(10001,"登录失败",null);
    }else {
        return new ResultVo(10000,"登录成功",user);
    }
}

在这里插入图片描述

4. @ApiModel 和 @ApiModelProperty

当接口参数和返回对象为对象参数时，在实体类中添加注解说明

在聚合工程中需要分别在相应的子工程中引入swagger2依赖

响应信息实体类（响应消息是对象时）

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "ResultVo对象",description = "封装接口返回给前端的数据")
public class ResultVo {

    @ApiModelProperty(value = "响应状态码",dataType = "int")
    private int code;
    @ApiModelProperty(value = "提示信息")
    private String msg;
    @ApiModelProperty(value = "响应数据")
    private Object data;
}

在这里插入图片描述

用户实体类（当用户注册请求参数是对象时）

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "User对象",description = "用户信息")
public class User {
    @ApiModelProperty(value = "用户ID",dataType = "int",required = false)
    private int userId;
    @ApiModelProperty(value = "用户姓名",dataType = "string",required = true)
    private String userName;
    @ApiModelProperty(value = "用户密码",dataType = "string",required = true)
    private String userPwd;
    @ApiModelProperty(value = "用户真实姓名",dataType = "string",required = true)
    private String userRealname;
    @ApiModelProperty(value = "用户头像url",dataType = "string",required = true)
    private String userImg;
}