SpringBoot中集成Swagger2

介绍

Swagger是非常流行的API框架，能够自动生成RESTFul 风格的API文档，还可以在线测试后台接口。
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，以及在线接口调试页面等等。
前后端分离的开发模式下，前端通过后端的API文档来进行开发和联调，效率更高。
Swagger就是帮助后端生成API文档的工具

简单使用

在SpringBoot中集成Swagger2，（等会说一个更简单的用法）。

1. 引入依赖

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.9.2version>
dependency>
<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.9.2version>
dependency>

2. 配置类

@Configuration
@EnableSwagger2
public class Swagger2Config {

    /**
     * 将负责生成摘要的Bean提供出去
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                //.enable(false)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("com.liumingkai.controller"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 用来设置文档元信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot中使用Swagger2接口规范")
                //文档描述
                .description("接口说明")
                //版本号
                .version("1.0.0")
                .build();
    }

}

3. 使用
   因为Swagger帮助我们生成RestFul风格的文档，所以被修饰的接口方法必须是类似于@GetMapping、@PostMapping、@DeleteMapping，不能是一个笼统的@RequestMapping
   下面会有详细的常用注解说明，此处只是想要来快速看一下效果

@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {

    @PostMapping("/login")
    @ApiOperation(value = "登录", tags = "登录接口")
    public String login(String username, String password){
        return "登录成功"+username+password;
    }

    @PostMapping("/logout")
    @ApiOperation(value="退出登录",tags = "退出登录")
    public String logout(String username){
        return "退出登录成功";
    }
}

接下来访问http://ip:port/swagger-ui.html，会看到

SpringBoot版本与Swagger版本的冲突问题

如果你访问Swagger的文档地址后，发现是404，无法访问，那么大概是SpringBoot的版本问题

注意：
如果你的SpringBoot是2.6.x及更高，那么与Swagger2是不兼容的，因为SpringMVC的处理映射匹配的方式发生了变化。
需要在SpringBoot的配置文件中通过添加配置来使springboot2.6.x以后的版本来适配Swagger2
不要试图通过@EnableWebMvc来解决，同样会导致404

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

参考文档：
SpringBoot与Swagger2版本不兼容的问题！！
Failed to start bean ‘documentationPluginsBootstrapper‘； nested exception is java.lang.NullPointerEx_Shipley_Leo的博客-CSDN博客
Springboot ✚ Swagger各版本整理_swaager 版本_qq_33334411的博客-CSDN博客
swagger-ui.html页面无法打开解决方案_Alphathur的博客-CSDN博客

常用注解

Swagger的核心就是我们常用的这几个注解

注解	说明
@Api	一般用在Controller类上，Swagger会扫描被此注解标注的类，并生成一个文档分类
@ApiOperation	用在接口方法上，对该接口方法进行描述
@ApiModel	用在实体类上，为此实体类生成说明文档
@ApiParam	用来接口参数上，用来对此请求参数做说明
@ApiModelProperty	用来实体类中的属性上，对此属性做说明

@Api

一般用来标注在Controller上，注意此Controller要是一个RestController。

@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {

}

属性：

• value ， 该接口模块的名称，没啥用，对于程序员来说起一个标识作用
• tags，该接口模块在文档中的标签名，会在API文档中显示。
  • 如果未指定此模块的tags标签，那么就会使用Controller的类名作为tags名称
  • tags可以认为是一个分类，名称相同的内容，会被归为一个分类。
• hidden，隐藏该模块，默认是false，不隐藏，隐藏后该模块不会出现在api文档中

@ApiOperation

次注解用在方法上，对该接口进行描述。

@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {

    @PostMapping("/login")
    @ApiOperation(value = "登录", tags = "用户登录接口")
    public String login(String username, String password){
        return "登录成功"+username+password;
    }

    @PostMapping("/logout")
    @ApiOperation(value="退出登录",tags = "用户登录接口")
    public String logout(String username){
        return "退出登录成功";
    }
}

属性：

• value，该接口方法的名称，必填的属性，用来对接口标识作用
• tags，用来指定该接口属于的标签，tags相同的接口方法，在文档中会属于同一个分类下
  • 一个接口方法可以属于多个分类
• hidden，是否隐藏该接口，默认是false
  

@ApiParam

用在接口的参数上，用来对该参数进行修饰
属性：

• value，标识作用
• name，该参数的名称，如果省略该属性，则会以参数名来作为名称在文档中显示
• required，是否必选，默认是false，此属性最常用

@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {

    @PostMapping("/login")
    @ApiOperation(value = "登录", tags = "用户登录接口")
    public String login(@ApiParam(name="username", required = true) String username, @ApiParam(name="password",required = true) String password){
        return "登录成功"+username+password;
    }

    @PostMapping("/logout")
    @ApiOperation(value="退出登录",tags = "用户登录接口")
    public String logout(String username){
        return "退出登录成功";
    }
}

@ApiResponse

用在方法上，对接口的返回内容进行描述
常用属性：

• code，响应的状态码
• message，返回的描述信息
• response，用来指定返回的实体类，也就是真正的响应数据

    @GetMapping("/detail/{username}")
    @ApiOperation("获取用户详情信息")
    @ApiResponse(code = 200,message = "查询成功",response = User.class)
    public User getDetail(@ApiParam(value = "要查询的用户名", required = true) @PathVariable("username") String username) {
        User user = new User();
        user.setAge(18);
        user.setUsername("zhagnsan");
        user.setPassword("123156");
        user.setSex("男");
        return user;
    }

@ApiResponses

如果返回的结果有多种，则可以使用@ApiResponses注解，此注解只有一个属性value，是一个@ApiResponse的数组。
其中包含多个@ApiResponse，每个@ApiResponse都是一种响应结果

    @GetMapping("/detail/{username}")
    @ApiOperation("获取用户详情信息")
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功", response = User.class),
            @ApiResponse(code = 403, message = "你还没有权限")
    }
    )
    public User getDetail(@ApiParam(value = "要查询的用户名", required = true) @PathVariable("username") String username) {
        User user = new User();
        user.setAge(18);
        user.setUsername("zhagnsan");
        user.setPassword("123156");
        user.setSex("男");
        return user;
    }

@ApiModel

用在实体类上，用来对此实体类进行描述。
如果你的返回值类型或参数类型是实体类类型，那么Swagger就会使用@ApiModel对其进行描述
属性：

• value，标识名，如果不填，则会以类名作为value
• description，类的描述信息
  实体类上标注了此类后，会将所有的属性进行描述

@ApiModel(value="用户实体类",description = "这是返回的实体类的描述信息")
@Data
public class User {

    private String username;

    private String password;

    private String sex;

    private Integer age;

}

一般都是直接@ApiModel注解，不用属性

@ApiProperty

如果需要对实体类中的属性进行单独的设置，那么就需要使用@ApiProperty属性了
常用属性：

• value，标识
• name，名称，在文档中的显示的名称
• hidden，是否隐藏此属性
• required，此属性是否必须

@ApiModel(value="用户实体类",description = "这是返回的实体类的描述信息")
@Data
public class User {

    @ApiModelProperty(value = "用户名",required = true)
    private String username;

    @ApiModelProperty(hidden = true)
    private String password;

    private String sex;

    private Integer age;

}