Swagger2 详解

1、Swagger2简介

当下很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发模式下，维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式。

2、依赖引入

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

3、启动类配置

在使用 Springboot 项目时，我们还需要在启动类添加 @EnableSwagger2 注解。
这个时候我们添加一个controller并写入方法，直接启动项目打开swagger-ui http://localhost:8080/swagger-ui.html

4、添加Swagger配置类

我们添加一个用于配置SwaggerUI的配置类。

    @Bean
    public Docket docket(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfo apiInfo = new ApiInfoBuilder().contact(new Contact("lzq","http://www.baidu.com","2645922971@qq.com"))
                .title("Lzq-Api")
                .description("Lzq-Api-Swagger-description")
                .version("1.0")
                .build();
        docket.apiInfo(apiInfo);
        return docket;
    }

还可添加指定扫描的包

        // 扫描指定包
        docket
                .select()
                // 方法上有注解@AnnoSwagger的时候返回true 最后取反
                .apis(Predicates.not(RequestHandlerSelectors.withMethodAnnotation(AnnoSwagger.class)))
                // 限制生成API文档的路径地址
                // 还可以使用 Predicates 的 and or 方法进行或且 运算
                .paths(PathSelectors.regex("/swagger/.*"))
                // 调用build重新构建
                .build();
                // 只能调一次 不可覆盖
                // .apis(RequestHandlerSelectors.basePackage("com.lzq.controller"));

并且这里的AnnoSwagger是一个自定义注解，用来限制Swagger文档不进行显示对应的方法

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface AnnoSwagger {
}

5、相关注解详解

5.1、@Api

tags 给当前类型定义别名 可以有多个，description 当前类型生成的帮助文档的描述信息

@Api(tags = {"hellloController", "SwaggerDemoController"}, description = "swagger-Api-controller")

5.2、@ApiOperation

用来描述方法

@ApiOperation(value = "hello", notes = "hello method get request")

5.3、@ApiParam

作用于入参，用来描述参数

@ApiParam(name = "用户名", value = "value - 用户名", required = true) String name

5.4、@ApiImplicitParam

作用于方法，用来描述参数

@ApiImplicitParam(name = "name", value = "name - value", required = true, paramType = "String")

5.5、@ApiImplicitParams

作用于方法，用来描述多个参数

    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "name", value = "name - value", required = true, paramType = "String"),
            @ApiImplicitParam(name = "PassWord", value = "PassWord - value", required = true, paramType = "String")
    })

5.6、@ApiIgnore

作用于方法，用来忽略生成该方法的Api文档

5.7、@ApiModel

作用于实体类，当成为帮助文档上的接口返回值类型时，即被解析

@ApiModel(value = "自定义实体类", description = "User Object")

5.8、@ApiModelProperty

作用于实体类对应的属性，进行描述

    @ApiModelProperty(value = "姓名 - value", name = "姓名 - name", required = false, example = "月月鸟", hidden = false)
    private String name;

6、Swagger-UI的使用

对于返回实体类可以在Models当中查看，其余方法（请求接口）在对应的controller类当中进行查看。

7、swagger2报错Illegal DefaultValue null for parameter type integer
这是由于实体类使用@ApiModelProperty时，example属性没有赋值导致的，在AbstractSerializableParameter的getExample方法中会将数值属性的example的转换数值类返回，example的默认值是""，因此当example没有赋值时，会出现上面的异常。

只需要在引入依赖时进行调整即可

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <!-- swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- 解决swagger报错Illegal DefaultValue null for parameter type integer -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>