官网：https://swagger.io/
swagger是一个文档在线自动生成器，它可以在线测试ApI,支持多种语言。之所以会产生这个框架，是因为在实际的项目开发过程中，前后端是分离的，他们之间通过API进行交互，但是由于两者之间无法做到实时的同步，可能会导致问题的发生。而swagger解决了上述问题，可以使得API实时在线更新，还可以在线测试。

1.集成Swagger

swagger3.0只需要引入这一个依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

如果是swagger2.x,需要导入下面的坐标

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

2.配置Swagger

由于很简单下面直接上代码

@Configuration //声明该类是一个配置类
@EnableSwagger2 //开启swagger
public class SwaggerConfig {
    /**
     * 创建Docket的bean实例对象
     * @return
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("user") // 配置分组
                .enable(true) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                //.any() // 扫描所有，项目中的所有接口都会被扫描到
                //.none() // 不扫描接口
                // 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
                //.withMethodAnnotation(final Class<? extends Annotation> annotation)扫描方法上的指定注解
                // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
                //.withClassAnnotation(final Class<? extends Annotation> annotation)
                //.basePackage(final String basePackage) // 根据包路径扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
                // 配置要拦截的路径，any:拦截所有，ant:拦截指定路径，none,都不拦截
                //.paths(PathSelectors.any())
                .build();
    }
    public ApiInfo getApiInfo(){
        //作者信息
        Contact DEFAULT_CONTACT = new Contact("hello", "https://www.xxx.com/", "625291936@qq.com");
        return  new ApiInfo(
                "项目文档", //标题
                "项目文档接口", //描述
                "1.0", //版本
                "https://www.xxx.com/", //项目地址
                DEFAULT_CONTACT, //作者信息
                "Apache 2.0", //许可
                "http://www.apache.org/licenses/LICENSE-2.0", //许可证网址
                new ArrayList<>());
    }
}

3.Swagger分组

只需要在上述controller中加入对应的Docket实例，并将其注入到spring中，在方法中修改groupName即可

//配置多个分组
@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("user1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("user2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("user3");
}  

4.输入网址测试

在网址栏中输入
swagger3 http://localhost:8080/swagger-ui/index.html
swagger2 http://localhost:8080/swagger-ui.html

注意：如果系统中有拦截器需要把webjars下以及swagger-ui.html等静态资源放行

registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

5.为Model添加swagger

如果我们想要为某个pojo类添加swagger信息，只需要书写对应的类，然后在controller接口中返回该对象就可以。
注意：User类中一定要有属性的setter，getter方法，否则，在后面的ui界面中不会显示User的属性，而且后面测试带参数的方法时，可能不能接收我们输入的值.

@ApiModel("User实体类")
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
    public String getUsername() {
        return username;
    }
    public void setUsername(String username) {
        this.username = username;
    }
    public String getPassword() {
        return password;
    }
    public void setPassword(String password) {
        this.password = password;
    }
}

测试

@ApiOperation("获取用户的controller")
    @GetMapping("/user")
    public User User() {
        return new User();
    }

6.Swagger的常用注解

在上述代码中或多或少都已经接触了swagger的常用注解，其实这些注解都是一些注释，他们的存在只是为了方便阅读与调试，如果嫌麻烦，甚至可以完全不用，但是在实际的项目中我们常常会使用他们，因此，掌握他们是非常有必要的，下面进行详解。

@Api: 修饰整个类，用于controller类上
@ApiOperation: 描述一个接口，作用于controller方法上
@ApiParam: 单个参数描述
@ApiModel: 用来对象接收参数,即返回对象
@ApiModelProperty: 对象接收参数时，描述对象的字段，用于entity类中的字段
@ApiResponse: Http响应其中的描述，在ApiResonse中
@ApiResponses: Http响应所有的描述，用在
@ApiIgnore: 忽略这个API
@ApiError: 发生错误的返回信息
@ApiImplicitParam: 一个请求参数
@ApiImplicitParams: 多个请求参数