一、swagger2介绍

swagger2是一个能用过注解的形式帮助我们生产api开发文档的工具包，同时也能够方便我们对api的一个实时管理和方便对api接口的调试，对于调用者也能更加直观发现问题，在api对接的过程中能提高我们对接时的效率。

效果图

二、spring boot集成swagger2使用

1. 添加入Swagger2的依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

2.Swagger2Config（Swagger2配置）

package com.example.swagger2demo.config;


import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Auther: yaohongan
 * @Date: 2019/10/4 20:14
 * @Description:Swagger2配置
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("demo")
                .apiInfo(apiInfo())
                .select()
                // 设置basePackage会将包下的所有类的所有方法作为api
//                .apis(RequestHandlerSelectors.basePackage("com.example.demo2.controller"))
                // 只有标记@ApiOperation才会暴露出给swagger
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.regex("/api/.*"))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API接口文档")
                .description("RESTful风格接口")
                .termsOfServiceUrl("https://blog.csdn.net/vbirdbest")  // 服务条款网址
                .version("1.0")
                .contact(new Contact("mengday", "httphttp://wwww.xxx.com", "[email protected]"))
                .build();
    }
}

3.PagerIDto（分页）

package com.example.swagger2demo.dto;

/**
 * @Auther: yaohongan
 * @Date: 2019/10/4 20:25
 * @Description:分页相关
 */
import io.swagger.annotations.ApiModelProperty;

public class PagerIDto {
    @ApiModelProperty(value = "页码", required = true)
    private int page;

    @ApiModelProperty(value = "每页条数", required = true)
    private int size;

    public PagerIDto() {
    }

    public int getPage() {
        return page;
    }

    public void setPage(int page) {
        this.page = page;
    }

    public int getSize() {
        return size;
    }

    public void setSize(int size) {
        this.size = size;
    }
}

4. 启动应用程序并访问swagger-ui.html

http://localhost:8080/swagger2demo/swagger-ui.html#/

三、为swagger-ui增加密码

1.pom.xml添加依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

2.application.yml添加配置

spring:
  security:
    basic:
      path: /swagger-ui.html
      enabled: true
    user:
      name: admin
      password: 123456

3.WebSecurityConfigurerAdapter（拦截器）

package com.example.swagger2demo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.WebSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

/**
 * Spring Security 会拦截swagger-ui.html 同样也会拦截api，这里将或略掉/api/下的所有子路径
 */
@EnableWebSecurity
@Configuration
class CustomWebSecurityConfigurerAdapter extends WebSecurityConfigurerAdapter {
    @Override
    public void configure(WebSecurity web) throws Exception {
        super.configure(web);
        web.ignoring().antMatchers("/api/v1/**");
    }
}

4.重启项目再次访问swagger-ui

访问 http://localhost:8080/swagger2demo/swagger-ui.html 会跳转到http://localhost:8080/swagger2demo/login 输入application.yml配置的用户名密码即可跳转到到swagger-ui.html

四、常用注解

@Api(description = “接口类的描述”)
@ApiOperation(value = “接口方法的名称”, notes = “备注说明”)
@ApiParam(name = “参数名称”, value = “备注说明”, required = 是否必须)：标注在方法的参数上 用于描述参数的名称、备注、是否必须等信息
@ApiImplicitParam(paramType = “query”, name = “password”, dataType = “String”, required = true, value = “密码”, defaultValue = “123456”)用于描述方法的参数，标注在方法上，和@ApiParam功能一样，只是标注的位置不同而已
   paramType：参数类型，即参数放在哪个地方
     header–>请求参数的获取：@RequestHeader，参数放在请求头
     query–>请求参数的获取：@RequestParam，参数追加在url后面
     path（用于restful接口）–>请求参数的获取：@PathVariable
     body 使用@RequestBody接收数据 POST有效，参数放在请求体中
     form
   name：参数名
   allowMultiple = true, 参数为数组List集合使用, 比如List< Order>: allowMultiple = true,                 
   dataType=“Order”
   dataType：参数的数据类型
   required：参数是否必须传
   value：参数的描述
   defaultValue：参数的默认值
@ApiImplicitParams： 用于包含多个@ApiImplicitParam
@ApiResponse(code = 0, message = “success”),
    code：响应码，例如400
    message：信息，一般是对code的描述
    response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：描述一个model的属性
        value 参数名称
        required 是否必须 boolean
        hidden 是否隐藏 boolean
@ApiIgnore：用于或略该接口，不生成该接口的文档
apis(RequestHandlerSelectors.basePackage(“com.example.demo2.controller”)) 会将包下的所有Controller类带有@RequestMapping或者XxxMapping都会给暴露给swagger，如果想部分类暴露出去部分不暴露出去，只能将不暴露的controller放到其他package中，放在同一个package是做不到的。

apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)): 只有在类上使用@Api注解标注并且在方法上使用@ApiOperation注解才会暴露给swagger，这种方式没有包名的限制，可以将需要暴露的接口分散到各个包里，只要类上有@Api注解方法上有@ApiOperation注解就能暴露出来，如果不想暴露出来就不用使用这两个注解。

参考文档：https://blog.csdn.net/vbirdbest/article/details/79680732