SpringBoot整合Swagger

目录

1.Swagger介绍
2.SpringBoot中快速使用Swagger
3.Swagger配置
4.Swagger通过注解描述文档

1.Swagger介绍

Swagger诞生的背景：

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。再次条件下，Swagger就孕育而生了😄。

Swagger官网地址：https://swagger.io/ 。

Swagger简介：

• Swagger号称世界上最流行的Api框架；
• Swagger是Restful Api 文档在线自动生成工具，Api文档与Api定义同步更新；
• 支持在线测试Api接口，相当于自带了一个postman工具；
• 支持多种语言。

2.SpringBoot中快速使用Swagger

导入依赖：

<!--        Swagger-->
        <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>

初步简单配置Swager：

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
}

这样简单配置后就可以是使用Swagger了，访问Swagger提供的UI界面http://localhost:8081/swagger-ui.html ，地址为：项目ip:端口号/swagger-ui.html。可以看到在UI界面显示了文档基础信息、控制器、控制器下对应的Api信息，实体类等信息。点击Api还可以进行在线请求测试。

3.Swagger配置

Swagger的配置相对来说也比较简单，我们只需要配置一个Swagger的Docket实例即可。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(Environment environment) {
        //判断当前环境同允许的环境是否匹配
        boolean enableSwagger = environment.acceptsProfiles(Profiles.of("dev","test"));
        //返回Docket实例
        return new Docket(DocumentationType.SWAGGER_2)
                //Api组名，我开发的是User模块，则可命名为UserApi；其他人开发的其他模块则以其他的组名配置新的Docket
                .groupName("UserApi")
                //是否使用Swagger，应该在开发环境使用，生产环境时不使用
                .enable(enableSwagger)
                //Api的Base路径，所有Api的前缀
                .pathMapping("/")
                //配置Api文档信息
                .apiInfo(apiInfo())
                .select()
                //配置要扫描的Api：controller包下的所有Api
                .apis(RequestHandlerSelectors.basePackage("cn.korb1n.springbootproject.controller"))
                //配置要扫描的路径：所有路径
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Korbin的Api文档")
                .description("这是这个Api文档的描述")
                .version("文档版本1.0")
                .termsOfServiceUrl("http://www.baidu.com?wd=服务条款网址")
                .contact(new Contact("Korbin","http://www.korbin.top","86744316@qq.com"))
                .license("商标品牌")
                .licenseUrl("http://www.baidu.com?wd=品牌官网")
                .extensions(new ArrayList<>()).build();
    }

}

在这个Docket的Bean中，配置了Swagger要映射路径、要扫描的接口的位置和要使用Swagger的环境；在apiInfo中，主要配置了一下Swagger2文档UI界面网站的信息，如网站的title，网站的描述，联系人的信息，使用的协议等等。

4.Swagger通过注解描述文档

配置好Swagger后，分类生成了Api接口，乍一看上去这个Api文档基本成型，但还缺少了对接口和实体类等的描述和注释，不然开发人员单看着这些接口，也很难知道接口的功能。

在Swagger中我们可以通过其提供的注解，非常便捷的给需要的地方加上描述，详细注解如下表：

注解	说明	参数
@Api	作用于类，表示这个类是个Controller控制器	value：类描述； tags：同样表示描述，但是值为数组
@ApiOperation	作用于方法，表示一个http请求的操作	value：方法描述；notes：内容提示；tags：可以重新分组（视情况而用）
@ApiParam	http请求方法的参数，字段说明；表示对参数添加元数据	name：参数名；value：参数说明；required：是否必填
@ApiModel	作用于类，表示这是一个实体类	value：实体类对象名；description：描述
@ApiModelProperty	用于方法、字段； 表示对model属性的说明或操作说明	value：字段说明；name：重写属性名字；dataType：重写属性类型；required：是否必须填写；example：举例说明；hidden：隐藏
@ApiIgnore	用于类或者方法上，可以不被swagger显示在页面上	无
@ApiImplicitParam	用于方法(表示单个参数)	name：参数名；value：参数说明；dataType：数据类型；paramType：参数类型；example：举例说明
@ApiImplicitParams	用于方法(表示多个参数)，包含多个 @ApiImplicitParam	@ApiImplicitParam

示例：

@ApiModel(value = "User",description = "用户信息实体类")
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
    @ApiModelProperty(value = "用户id",example = "100000")
    @TableId(type = IdType.AUTO)
    private Long id;
}


@Api(tags = "用户控制器")
@RestController
public class UserController {

    @Autowired
    private UserMapper userMapper;

    @ApiOperation(value = "按照id查找用户")
    @GetMapping("/user")
    public User findById(@ApiParam(name = "id",value = "用户id") Long id){
        return userMapper.selectById(id);
    }
}

可以看到Api文档的描述信息发生改变了：

注意：如果例如上述的id字段为Long，但是在注解中没有写明example参数，会默认id的值为空字符串，就会报错：