SpringBoot整合swagger2

swagger简介

Swagger 就是一种可以帮助我们简化 API 开发过程的工具。
API:在业界，API 一般指的是：通过后端编码而开发出来的，且可以供其他用户所使用的一种专门对外暴露的数据传输接口，即我们可以通过编写 API 来达到和用户交互的目的。

SpringBoot 集成 Swagger-UI

(1) . 在maven导入集成依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
         <swagger.version>2.9.2</swagger.version>

(2) . 在 SpringBoot 中配置 Swagger-UI

/**
 * @author 王振宇
 * Date: Created in 18/8/29 上午9:54
 * Utils: Intellij Idea
 * Description: swagger 配置信息
 */
@Data
@Component
@ConfigurationProperties(prefix = "swagger")
//@ConfigurationProperties 和 @value 有着相同的功能,但是 @ConfigurationProperties的写法更为方便
public class SwaggerInfo {
    /**
     * 标题
     */
    private String title;
    /**
     * 简介
     */
    private String description;
    /**
     * 分组名称
     */
    private String groupName;
    /**
     * 版本
     */
    private String version;
    /**
     * 扫描的包路径
     */
    private String basePackage;
    /**
     * 接口作者
     */
    private String author;
}

以及核心配置类

/**
 * @author 王振宇
 * Date: Created in 2020-04-02
 * Utils: Intellij Idea
 * Description: swagger配置类
 */
@Configuration  //让Spring来加载该类配置
@EnableSwagger2 //开启swagger
@Profile({"dev", "test"}) //表明swagger只能使用在dev test 也就是开发和测试阶段
@EnableConfigurationProperties(SwaggerInfo.class)
public class SwaggerConfiguration {

    private SwaggerInfo swaggerInfo;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(swaggerInfo.getGroupName())
                .useDefaultResponseMessages(false)
                .enableUrlTemplating(false)
                .forCodeGeneration(true)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerInfo.getBasePackage()))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 设置api信息
     *
     * @return 返回ApiInfo
     */
    private ApiInfo apiInfo() {
        StringVendorExtension vendorExtension = new StringVendorExtension("", "");
        Collection<VendorExtension> vendorExtensions = new ArrayList<>();
        vendorExtensions.add(vendorExtension);
        Contact contact = new Contact("", "", "");
        return new ApiInfo(
                swaggerInfo.getTitle(),
                swaggerInfo.getDescription(),
                swaggerInfo.getVersion(),
                "", contact, "", "",
                vendorExtensions);
    }

}

配置类createRestApi()解释:
①createRestApi 方法的返回值是一个 Docket 类型，该类型就是返回 Swagger-Documentation 类型的数据，大家不用关心
②在方法内部，使用匿名内部类的方式实例化了一个 Docket 对象并返回，DocumentationType 即文档类型的选择我们需要根据集成的 Swagger 的版本来选择，这里选择 SWAGGER_2 表示使用的 Swagger 是2.X系列版本。
③apiInfo() 和 select() 这两个方法是配置 Swagger 应用的必要方法，我们只需要这样理解就可以了集成必要的 API 信息（apiInfo() 方法）来供我们查询（select() 方法）使用。
④apis() 方法里面通过 RequestHandlerSelectors.basePackage() 属性来描述我们的目标包，就是我们项目中接口所在包的完整目录名称，这样 Swagger 就可以扫描到了，如果不配置此项，Swagger 是 扫描不到我们项目中的接口的。
⑤paths() 方法就是规定将我们项目中所有接口的请求路径都暴露给 Swagger 来生成 Swagger-UI 界面。
⑥build() 方法就是将我们设置的上述参数都放到返回的 Docket 实例中。
配置类apiInfo()解释:

①apiInfo 方法返回 Swagger-ApiInfo 类型，大家可以理解为返回 Swagger-UI 界面的基本信息就行了。在方法内部也是通过匿名内部类的方式返回一个 ApiInfo 实例。
②title() 方法：就是来规定我们的 Swagger-UI 界面的大标题。
③description() 方法：就是来规定对 Swagger-UI 界面的一些简单描述信息。
④contact() 方法：就是来规定创建 Swagger-UI 的作者的名称，目前已被废弃。
⑤version() 方法：就是来规定 Swagger-UI 界面上所有接口的版本
⑥**build() 方法：就是将我们设置的上述参数都放到返回的 ApiInfo 实例中。

(3). yml中的配置 和 SwaggerInfo类对应

# 配置swagger
swagger:
  version: 2.0
  groupName: 基础项目
  title: 基础项目
  description: 接口文档
  # 扫描的包路径
  basePackage: com.basic.com.controller

注意: @ConfigurationProperties注解 和 @EnableConfigurationProperties注解的关系

(4) . 使用swagger2

启动项目之后，在浏览器地址栏中输入访问路径（一般为项目 ip 地址：端口/swagger-ui.html）

swagger注解介绍

(1) . Swagger-Api 注解

①Api 注解是作用
在接口类上面的注解，其主要是用来给接口类定义相关说明
②Api注解的主要属性

③
该属性就是对实现相同业务功能的接口类做一个大型的分组，该分组中包括同业务功能下的所有的接口。
注意: 现在很少有人使用value()这个属性,一般都用tags()来代替,当两者同时出现的时候,tags属性值会把values属性值代替**

@Api(value="user-controller", tags = {"用户操作"})
public class UserController{
    // do something...
}

启动后显示:黑色加粗

④description()属性
该属性就是对接口类进行简单概要的描述，通常是描述一些注意的地方，value 属性更多的则是描述接口类的用途

@Api(tags = {"用户操作"},description = {"业务用户的增删改查"})
public class UserController{
    // do something...
}

(2) . Swagger-ApiOperation 注解

①ApiOperation 注解是作用
ApiOperation 注解提供了丰富的属性来允许我们自定义接口描述信息，包括接口名称，接口所属分组等
也就是注解写在方法上的
②ApiOperation 注解的主要属性

③value()属性
方法的上方使用了 @ApiOperation 的 value 属性来描述接口的作用。

    /**
     * 添加用户
     * @param userForm 表单数据
     * @return 成功或者失败
     */
    @ApiOperation(value = "添加用户")
    @PostMapping("/addUser")
    public ResultVo addUser(@Validated @RequestBody AddUserForm userForm){
        if(userService.addUser(userForm)){
            return ResultVoUtil.success();
        }else{
            return ResultVoUtil.error(ResultEnum.ADD_ERROR);
        }
    }

启动后