[Swagger]-Swagger学习

参考视频链接
官方文档链接

1.导入依赖

    io.springfox
    springfox-swagger2
    2.9.2



    io.springfox
    springfox-swagger-ui
    2.9.2

2.创建Swagger配置类

@EnableSwagger2  //开启Swagger2
@Configuration   //标志该类是项目的配置类
public class Swagger2Config {
}

3.访问项目的swagger-ui.html就是ui界面

可以看到ui界面大体可以分为四部分：选择框，api信息，控制层请求接口信息以及项目的model实体类信息

swagger的配置需要一个Docket类的bean。而Docket类的构造函数只有一个：

public Docket(documentationType documentationType) {
    this.apiInfo = ApiInfo.DEFAULT;
    ......
    this.documentationType = documentationType;
}

documentationType类中有三个static final修饰的documentationType变量：

public class documentationType extends SimplePluginmetadata {
    public static final documentationType SWAGGER_12 = new documentationType("swagger", "1.2");
    public static final documentationType SWAGGER_2 = new documentationType("swagger", "2.0");
    public static final documentationType SPRING_WEB = new documentationType("spring-web", "1.0");
    ...
}

所以Docket的构造函数只需传入documentationType.SWAGGER_2即可。这样构造出Docket后其中的属性都是默认的，可使用其中的方法对属性进行配置
如apiInfo方法可以配置api信息；enable方法可以指定是否开启Swagger；groupName方法可以指定该docket的接口api的组名；tags方法可以配置某些标签，可以在描述控制器的名称或描述信息等时使用(后续的@Api注解)；forCodeGeneration方法可以设置泛型在编码时的格式，具体在文档中的描述是这样的：

Docket中的apiInfo方法可以配置api的信息。该方法需要传入一个ApiInfo类对象，该类中包括以下信息：

private final String version;                         //项目版本号
private final String title;                           //项目标题
private final String description;                     //项目等的描述
private final String termsOfServiceUrl;               //服务条款url
private final String license;                         //证书
private final String licenseUrl;                      //证书url  
private final Contact contact;                        //联系人  
private final List vendorExtensions; //其它扩展信息

ApiInfo类中只提供了全参构造器以及各属性的get方法没有set方法，所以可以使用全参构造器构造ApiInfo类对象。除此之外可以使用ApiInfoBuilder类来构造ApiInfo，借助ApiInfoBuilder可以通过单个方法设置ApiInfo的各项属性，比直接调用ApiInfo类的全参构造器就更灵活且简洁，设置完属性调用build方法就可以返回一个ApiInfo对象，该方法实际上也是在调用ApliInfo的全参构造方法

通过Docket中的tags方法可以设置标签，该方法接收一个Tags对象，一般使用Tag(String name, String description)构造方法构造，指定tag的名称以及该tag要描述的信息。被构造出来的标签不管有没有被使用到类或方法上都会在ui界面上显示出来
使用时只需在控制器类上加@Api注解，然后将其中的tags属性指定为某个Tags的name属性即可将这个类与这个标签绑定在一起
当然请求方法也可以跟某个tags绑定在一起，但是这样的话会造成方法跟类之间没有层级关系而是平行关系，可读性降低了

通过Docket的select方法会得到该Docket的ApiSelectorBuilder类对象，该对象就是用于配置api接口信息的
通过apis方法指定扫描接口的方式，该方法接受一个泛型为RequestHandler接口类型的Predicate接口参数，RequestHandlerSelectors类中对此有具体的实现：basePackage方法可以指定扫描某个包下的请求接口；any扫描全部接口；none都不扫描；withClassAnnotation扫描有指定注解的类中的接口；withMethodAnnotation扫描有指定注解的方法上的接口
通过paths可以指定扫描哪些请求路径，类似于apis方法，该方法调用PathSelectors类中的方法作为参数：any指定扫描所有请求路径；none不扫描任何路径；ant方法接收一个字符串路径模式(如"/**")，指定扫描符合该指定模式的路径；regex方法接收一个正则表达式，指定扫描符合正则表达式的路径
接口的扫描指定好后，调用build方法即可得到原先的Docket
@ApiIgnore用于类或方法或参数上，表示被注解的项要被忽略

@Api用在类上，添加整个类中的所有接口的描述信息(使用tags属性)
@ApiOperation用在方法上，添加方法(请求接口)的描述信息
@ApiParam用在方法参数(请求参数)前面，添加参数的描述信息以及参数是否必须等

一个项目中可以设定多个Docket，每个Docket配置自己的组名，接口api信息等其它性质，不同Docket的接口就是不同组的，在ui界面的选择框可以选择不同组别进行展示

只要控制层请求接口的返回值存在实体类，它就会被扫描到swagger中
在实体类上加注解@ApiModel可以添加实体类的描述信息
在实体类中的成员变量上加注解@ApiModelProperty可以添加字段的描述信息(如果成员变量是public修饰直接这样就可以，如果是private修饰就需要加上get和set方法才能生效)

swagger配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket(){
        return new Docket(documentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("这里是GroupName")
                .forCodeGeneration(true)
                .tags(new Tag("这是标签的名字","这是标签对应要描述的信息"))
                .tags(new Tag("这个标签创建了但是没有使用","还是会显示出来"))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.www.testcontroller"))
                //.paths(PathSelectors.ant("/test/*"))
                .build();
    }
    @Bean
    public Docket docket2(){
        return new Docket(documentationType.SWAGGER_2)
                .groupName("这里是第二个GroupName");
    }
    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("这里是title")
                .version("这里是version")
                .description("这里是description")
                .build();
    }
}

控制器

@Api(value = "这是类",tags = {"这是标签的名字"})
@RestController
@RequestMapping("/test")
public class TestController {
    @ApiOperation(value = "这是接口描述")
    @GetMapping("/testUser")
    public List test(List result) {
        return new ArrayList();
    }
}

ui界面

正式发布时应关闭swagger，出于安全考虑，避免暴露接口，同时节约运行所需资源
swagger在代码层面需要做配置，注解等，具有一定的代码植入性