注：看了狂神说自己所作的笔记  狂神说的笔记https://mp.weixin.qq.com/s/0-c0MAgtyOeKx6qzmdUG0w
 
学习目标
 
了解Swagger的作用和概念
了解前后端分离
在Springboot中集成Swagger
 Swagger
 
前后端分离
 
Vue+Springboot
 
后端时代：前端只用管前端静态页面；后端要htmk和jsp渲染数据。
 
前后端分离时代
 
后端：后端控制层，服务层，数据访问层
前端：前端控制层，视图层   
伪造后端数据，json。已经存在了，不需要后端前端就可以单独运行
前后端如何交互？===API
前后端先对独立，松耦合
前后端可以部署在不同的服务器
产生了问题
 
前后端联调，前后端无法做到“即使协商，尽早解决“，最终导致问题集中爆发.
首先制定schema【计划的提纲】，实时更新最新的Api，降低集成风险；
早期：制定word计划文档；
前后端分离
前端测试后端接口：postman
后端提供接口，需要实时更新最新的消息改动
Swagger
 
世界上最流行的Api框架
RestFul Api 文档在线自动生成工具=API文档与API定义同步更新
直接运行，可以在线测试API接口
支持多种语言（java，php）
在项目中使用springfox；
 
swagger2
ui
SpringBoot集成Swagger2
 
1.新建springboot项目
 
2.pom导入swagger2的maven配置
 
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<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>
---------------------------------------------------------------------------------------
	<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.10.5</version>
		</dependency>

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.10.5</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-spring-webmvc</artifactId>
			<version>2.10.5</version>
		</dependency>



2.9.2  和  2.10.5 有差别的需要多导入一个jar 不然会报一个错
@EnableSwagger2这个注解不能使用了 换成@EnableSwagger2WebMvc
 
3.配置swagger配置文件
 
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
}
 
4.访问测试页面http://localhost:8080/swagger-ui.html
 
 
 
配置Swagger
 
1、Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。
 
@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}


----------------------------------------

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}


//配置文档信息
private ApiInfo apiInfo() {
   Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
   return new ApiInfo(
           "Swagger学习", // 标题
           "学习演示如何配置Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/组织链接", // 组织链接
           contact, // 联系人信息
           "Apach 2.0 许可", // 许可
           "许可链接", // 许可连接
           new ArrayList<>()// 扩展
  );
}
 
配置扫描接口
 
1、构建Docket时通过select()方法配置怎么扫描接口。
 
@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
      .build();
}

--------------------------------------------------------
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) // 根据包路径扫描接口
 
配置Swagger开关
 
1、通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}
2、如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

@Bean
public Docket docket(Environment environment) {
   // 设置要显示swagger的环境
   Profiles of = Profiles.of("dev", "test");
   // 判断当前是否处于该环境
   // 通过 enable() 接收此参数判断是否要显示
   boolean b = environment.acceptsProfiles(of);
   
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(b) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}
 
配置API分组
 
 
 
1、如果没有配置分组，默认是default。通过groupName()方法即可配置分组
@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}
2、重启项目查看分组

3、如何配置多个分组？配置多个分组只需要配置多个docket即可：

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
 
注解
 
@Data
@ApiModel("角色模型")
public class Role {
    @ApiModelProperty("角色名称")
    private String rolename;
    @ApiModelProperty("用户ID")
    private String userId;
}

@RestController
@Api(value="用户controller",tags={"用户操作接口"})
public class HelloController {
    @ApiOperation("说你好")
    @GetMapping("hello")
    public Role sayHello(User user,@ApiParam("密码") String password,Role role)
    {
        User user1 = new User();
        user1.setAge("11");
        user1.setUsername("gene");
        return role;
    }
}
 

一、SpringBoot集成Swagger2
 
1.1、导入两个springfox的jar包
 
Springfox-Swagger2
Swagger-Springmvcs
 
二、使用Swagger
 
 
 
要求：jdk 1.8 + 否则Swagger2无法运行
 
 
步骤：
 
 
 
2.1、新建一个SpringBoot-web项目
 
 
 
 
2.2、添加Maven依赖
 
 
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<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.3、编写HelloController，测试确保运行成功！
 
 
 
 
2.4、要使用Swagger，我们需要编写一个配置类SwaggerConfig来配置 Swagger
 
 
@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
}
 
 
 
2.5、访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；
 
 
 
三、配置Swagger
 
 
 
3.1、Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。
 
 
@Configuration //定义Java配置类
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2);
    }
}
 
 
 
3.2、可以通过apiInfo()属性配置文档信息
 
 
//配置Swagger的apiInfo信息
    @Bean
    public ApiInfo apiInfo(){
        //作者信息
        Contact CONTACT = new Contact("未进化的程序猿", "https://www.cnblogs.com/the-undeveloped-procedural-ape/", "486566947@qq.com");
        return new ApiInfo("未进化的程序猿的Swagger日志", //Swagger文档标题
                           "Api Documentation",//Swagger文档描述
                           "v1.0",//Swagger文档版本号
                           "https://www.cnblogs.com/the-undeveloped-procedural-ape/",//博客地址
                           CONTACT,//作者信息
                           "Apache 2.0",
                           "http://www.apache.org/licenses/LICENSE-2.0",
                           new ArrayList());
    }
 
 
 
3.3、Docket 实例关联上 apiInfo()
 
 
@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
 
 
 
3.4、重启项目，访问测试 http://localhost:8080/swagger-ui.html；
 
 
四、配置扫描接口
 
 
 
4.1、构建Docket时通过select()方法配置怎么扫描接口。
 
 
//往容器中注入一个Docket
    //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");

        //获取项目的环境
        //通过environment.acceptsProfiles(profiles): 判断是否是自己设定的环境处于自己设定的环境当中
        boolean acceptsProfiles = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo()) //Swagger的基本信息
                    .groupName("未进化的程序猿") //分组的名称
                    .enable(acceptsProfiles) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                    .select() //配置Swagger扫描接口
                    //RequestHandlerSelectors配置Swagger扫描接口的方式
                    //basePackage("扫描的包路径")
                    //any(): 扫描全部
                    //none(): 都不扫描
                    //withClassAnnotation(Controller.class): 扫描类上的注解
                    //withMethodAnnotation(GetMapper.class): 扫描方法上的注解
                    .apis(RequestHandlerSelectors.basePackage("com.example.springbootswagger.controller"))
                    //paths(): 过滤什么路径
                    //PathSelectors.ant("/"): 过滤要求
                    //.paths(PathSelectors.ant("/"))
                    .build();
    }
 
 
 
4.2、重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类
 
 
 
 
4.3、除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：
 
 
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) // 根据包路径扫描接口
 
 
 
4.4、除此之外，我们还可以配置接口扫描过滤：
 
 
@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}
 
 
 
4.5、这里的可选值还有
 
 
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制
 
五、配置Swagger开关
 
 
 
5.1、通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了
 
 
@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}
 
 
 
5.2、如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？
 
 
 
 
 
application.properties
 
 
 
 
 
application-dev.properties
 
 
 
 
 
application-pro.properties
 
 
 
//往容器中注入一个Docket
    //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");

        //获取项目的环境
        //通过environment.acceptsProfiles(profiles): 判断是否是自己设定的环境处于自己设定的环境当中
        boolean acceptsProfiles = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo()) //Swagger的基本信息
                    .groupName("未进化的程序猿") //分组的名称
                    .enable(acceptsProfiles) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                    .select() //配置Swagger扫描接口
                    //RequestHandlerSelectors配置Swagger扫描接口的方式
                    //basePackage("扫描的包路径")
                    //any(): 扫描全部
                    //none(): 都不扫描
                    //withClassAnnotation(Controller.class): 扫描类上的注解
                    //withMethodAnnotation(GetMapper.class): 扫描方法上的注解
                    .apis(RequestHandlerSelectors.basePackage("com.example.springbootswagger.controller"))
                    //paths(): 过滤什么路径
                    //PathSelectors.ant("/"): 过滤要求
                    //.paths(PathSelectors.ant("/"))
                    .build();
    }
 
 
 
5.3、可以在项目中增加一个dev的配置文件查看效果！
 
 
 
六、配置API分组
 
 
 
 
6.1、如果没有配置分组，默认是default。通过groupName()方法即可配置分组：
 
 
@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}
 
 
 
6.2、重启项目查看分组
 6.3、如何配置多个分组？配置多个分组只需要配置多个docket即可：
 
 
@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
 
 
 
6.4、重启项目查看即可
 
 
七、实体配置
 
 
 
7.1、新建一个实体类
 
 
@ApiModel("用户实体")
public class User {
   @ApiModelProperty("用户名")
   public String username;
   @ApiModelProperty("密码")
   public String password;
}
 
 
 
7.2、只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：
 
 
@RequestMapping("/getUser")
public User getUser(){
   return new User();
}
 
 
 
7.3、重启查看测试
 
 
 
 
 
注意：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。
 
 
 
 
@ApiModel为类添加注释
 @ApiModelProperty为类属性添加注释
 
 
八、常用注解
 
 
 
Swagger的所有注解定义在io.swagger.annotations包下
 下面列一些经常用到的，未列举出来的可以另行查阅说明：
 
 
 
 
 
我们也可以给请求的接口配置一些注释
 
 
@ApiOperation("未进化的程序猿的接口")
@PostMapping("/kuang")
@ResponseBody
public String index(@ApiParam("这个名字会被返回")String username){
   return username;
}
 
九、SpringBoot集成Swagger 配置
 
package com.example.springbootswagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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;

import java.util.ArrayList;

@Configuration //定义Java配置类
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    //创建多个组实例
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("张三");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("李四");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("王五");
    }

    //往容器中注入一个Docket
    //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");

        //获取项目的环境
        //通过environment.acceptsProfiles(profiles): 判断是否是自己设定的环境处于自己设定的环境当中
        boolean acceptsProfiles = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo()) //Swagger的基本信息
                    .groupName("未进化的程序猿") //分组的名称
                    .enable(acceptsProfiles) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                    .select() //配置Swagger扫描接口
                    //RequestHandlerSelectors配置Swagger扫描接口的方式
                    //basePackage("扫描的包路径")
                    //any(): 扫描全部
                    //none(): 都不扫描
                    //withClassAnnotation(Controller.class): 扫描类上的注解
                    //withMethodAnnotation(GetMapper.class): 扫描方法上的注解
                    .apis(RequestHandlerSelectors.basePackage("com.example.springbootswagger.controller"))
                    //paths(): 过滤什么路径
                    //PathSelectors.ant("/"): 过滤要求
                    //.paths(PathSelectors.ant("/"))
                    .build();
    }

    //配置Swagger的apiInfo信息
    @Bean
    public ApiInfo apiInfo(){
        //作者信息
        Contact DEFAULT_CONTACT = new Contact("未进化的程序猿", "https://www.cnblogs.com/the-undeveloped-procedural-ape/", "486566947@qq.com");
        return new ApiInfo("未进化的程序猿的Swagger日志", //Swagger文档标题
                           "Api Documentation",//Swagger文档描述
                           "v1.0",//Swagger文档版本号
                           "https://www.cnblogs.com/the-undeveloped-procedural-ape/",//博客地址
                            DEFAULT_CONTACT,//作者信息
                           "Apache 2.0",
                           "http://www.apache.org/licenses/LICENSE-2.0",
                           new ArrayList());
    }

}
 
总结：
 
 
 
1）、这样的话，可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！
 
 
 
 
2）、相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。
 
 
 
 
3）、Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。
 

 
SpringBoot集成Swagger2与Swagger3的区别
 
前言
一、pom文件中引入Swagger依赖
Swagger2
Swagger3
  
二、Swagger配置
Swagger2
Swagger3
  
三、若配置有拦截器，应对Swagger做如下配置
Swagger2
Swagger3
  
四、若项目中还有Token验证，则对应Swagger配置文件做如下修改
Swagger2
Swagger3
  
五、访问路径
Swagger2和Swagger3的访问路径也有所不同
  
总结

 
前言
 
 Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。 





 
一、pom文件中引入Swagger依赖
 
Swagger2
 
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.7.0</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.7.0</version>
</dependency>
 
Swagger3
 
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>
 



 
二、Swagger配置
 
Swagger2
 
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 自行修改为自己的包路径
                .apis(RequestHandlerSelectors.basePackage("com.tsing"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-api文档")
                .description("swagger接入教程")
                .version("1.0")
                .contact(new Contact("TheTsing", "https://blog.csdn.net/qq_42375133?type=blog", "thetsing@foxmail.com"))
                .build();
    }

}
 
Swagger3
 
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.tsing"))
                .paths(PathSelectors.any())
                .build()
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Api Documentation")
                .contact(new Contact("TheTsing", "http://www.baidu.com", "thetsing@foxmail.com"))
                .version("1.0")
                .build();
    }

}
 



 
三、若配置有拦截器，应对Swagger做如下配置
 
Swagger2
 
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 配置swagger拦截器
        registry.addInterceptor(new MyInterceptor())// 这里加入自己写的拦截器
                .addPathPatterns("/**").
                excludePathPatterns("/swagger-resources/**", "/webjars/**", "/swagger-ui.html/**", "/v2/**");
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 配置swagger静态资源映射
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        // 跨域支持
        registry.addMapping("/**").allowedOriginPatterns("*").allowedMethods("*").allowCredentials(true);
    }

}
 
Swagger3
 
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 配置swagger拦截器
        registry.addInterceptor(new MyInterceptor())
                .addPathPatterns("/**").
                excludePathPatterns("/swagger-resources/**", "/webjars/**", "/swagger-ui/**", "/v3/**");
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 配置swagger静态资源映射
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        // 跨域支持
        registry.addMapping("/**").allowedOriginPatterns("*").allowedMethods("*").allowCredentials(true);
    }

}
 



 
四、若项目中还有Token验证，则对应Swagger配置文件做如下修改
 
Swagger2
 
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 自行修改为自己的包路径
                .apis(RequestHandlerSelectors.basePackage("com.tsing"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-api文档")
                .description("swagger接入教程")
                .version("1.0")
                .contact(new Contact("TheTsing", "https://blog.csdn.net/qq_42375133?type=blog", "thetsing@foxmail.com"))
                .build();
    }

    private List<ApiKey> securitySchemes() {
        List<ApiKey> apiKeyList = new ArrayList();
        apiKeyList.add(new ApiKey("token", "token", "header"));
        return apiKeyList;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex("^(?!auth).*$"))
                .build());
        return securityContexts;
    }

    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("token", authorizationScopes));
        return securityReferences;
    }

}
 
Swagger3
 
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.tsing"))
                .paths(PathSelectors.any())
                .build()
                .protocols(newHashSet("https", "http"))
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Api Documentation")
                .contact(new Contact("TheTsing", "http://www.baidu.com", "thetsing@foxmail.com"))
                .version("1.0")
                .build();
    }

    /**
     * 设置授权信息
     */
    private List<SecurityScheme> securitySchemes() {
        ApiKey apiKey = new ApiKey("token", "token", In.HEADER.toValue());
        return Collections.singletonList(apiKey);
    }

    /**
     * 授权信息全局应用
     */
    private List<SecurityContext> securityContexts() {
        return Collections.singletonList(
                SecurityContext.builder()
                        .securityReferences(Collections.singletonList(new SecurityReference("token", new AuthorizationScope[]{new AuthorizationScope("global", "accessEverything")})))
                        .build()
        );
    }

    @SafeVarargs
    private final <T> Set<T> newHashSet(T... ts) {
        if (ts.length > 0) {
            return new LinkedHashSet<>(Arrays.asList(ts));
        }
        return null;
    }

}
 



 
五、访问路径
 
Swagger2和Swagger3的访问路径也有所不同
 
Swagger2：http://localhost:port/swagger-ui.html
 Swagger3：http://localhost:port/swagger-ui/index.html
 

 
总结
 
 如果这篇博客对你有帮助的话，记得给我点个赞，你的鼓励是对我最大的支持！谢谢｡◕‿◕｡ 

 
前言：目前互联网开发市场都流行前后台真正的分离，后台提供数据API接口，前台负责请求数据并渲染。那么我们程序猿们在编写接口的时候，最不方便之处就是写完接口后需要进行文档的编写以及接口的测试。今天就介绍一款将接口文档编写和测试合并一起的集大成者Swagger，也是目前很多企业再用的一个API管理工具。此DEMO的开发环境是：MAVEN + Spring Boot 2.1.0 + JDK8 + Swagger2.9.2
 
1、快速构建Spring Boot项目
 
在https://start.spring.io/中选择Maven构建Java项目，然后选用Spring Boot2.1.0版本，Group是com.mage，Artifact是swagger_restful，Dependencies选择web，这样就能快速构建一个基于Spring Boot的web项目了。如下图：
 

 
2、使用IDEA打开项目
 
解压swagger_restful.zip，然后使用idea导入项目，并执行SwaggerRestfulApplication.java，不报错说明项目构建成功
 

 
3、pom导入swagger2的依赖jar包
 
io.springfox
 
springfox-swagger2
 
2.9.2
 
​
 
io.springfox
 
springfox-swagger-ui
 
2.9.2
 
5、编写测试的Controller和Model(TestController和Test)
 
编写一个Test的数据模型
 
package com.mage.swagger_restful.model;
 
​
 
public class Test {
 
private Integer id;
 
private String content;
 
private Integer isValid;
 
​
 
public Integer getId() {
 
return id;
 
}
 
​
 
public void setId(Integer id) {
 
this.id = id;
 
}
 
​
 
public String getContent() {
 
return content;
 
}
 
​
 
public void setContent(String content) {
 
this.content = content;
 
}
 
​
 
public Integer getIsValid() {
 
return isValid;
 
}
 
​
 
public void setIsValid(Integer isValid) {
 
this.isValid = isValid;
 
}
 
}
 
基于Restful规则，编写一组测试的API接口：
 
package com.mage.swagger_restful.controller;
 
​
 
import org.springframework.web.bind.annotation.*;
 
​
 
@RestController
 
@RequestMapping("test")
 
public class TestController {
 
​
 
@GetMapping("")
 
public String list() {
 
return "查询列表数据!";
 
}
 
​
 
@GetMapping("{id}")
 
public String find(@PathVariable Integer id) {
 
return String.format("根据主键查询数据: %d", id);
 
}
 
​
 
@PostMapping("")
 
public String add() {
 
return "插入数据!";
 
}
 
​
 
@PutMapping("{id}")
 
public String update(@PathVariable Integer id) {
 
return String.format("根据主键更新一条记录: %d", id);
 
}
 
​
 
@DeleteMapping("{id}")
 
public String delete(@PathVariable Integer id) {
 
return String.format("根据主键删除记录: %d", id);
 
}
 
}
 
因为接口是基于Restful(本文不讨论Restful的编写规范)编写，所以如果单纯利用浏览器输入是没法进行接口测试的，比如模拟post, put或者delete请求，这时要测试可以借助一些浏览器的插件比如postman或者rested等。这样我们还要额外去安装工具，显得比较麻烦，同时工作中写完接口后，一般还会编写接口文档，那么聪明的码农就想着能不能优化这个流程，让接口测试和接口文档编写变得简单快捷，于是乎，swagger应用而生。
 
6、代码中集成Swagger
 
a) 编写Swagger的配置类
 
package com.mage.swagger_restful.config;
 
​
 
import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
 
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.spi.DocumentationType;
 
import springfox.documentation.spring.web.plugins.Docket;
 
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
​
 
@Configuration
 
@EnableSwagger2
 
@ConditionalOnExpression("${swagger.enable:true}")
 
public class SwaggerConfig {
 
​
 
@Bean
 
public Docket createDocket(){
 
​
 
Docket docket = new Docket(DocumentationType.SWAGGER_2)
 
.apiInfo(new ApiInfoBuilder().title("码歌学院API")
 
.description("码歌学院相关接口API文档")
 
.version("1.0").build())
 
.select()
 
.apis(RequestHandlerSelectors.basePackage("com.mage"))
 
.paths(PathSelectors.any())
 
.build();
 
return docket;
 
}
 
​
 
}
 
其中@EnableSwagger2开启Swagger2功能，是swagger2的注解，@ConditionalOnExpression("${swagger.enable:true}")当配置文件中swagger.enable为true时才启用swagger2，是spring boot注解，方便区分不同环境下是否启用swagger2。
 
b) 修改application.properties
 
swagger.enable=true
 
c) 修改Test实体模型和TestController，添加Swagger对应注解
 
修改Test实体模型：
 
package com.mage.swagger_restful.model;
 
​
 
import io.swagger.annotations.ApiModel;
 
import io.swagger.annotations.ApiModelProperty;
 
​
 
@ApiModel(description = "测试模型实体")
 
public class Test {
 
@ApiModelProperty(name = "id", value = "主键", hidden = true)
 
private Integer id;
 
@ApiModelProperty(name = "content", value = "测试内容")
 
private String content;
 
@ApiModelProperty(name = "isValid", value = "是否有效0=无效，1=有效", hidden = true)
 
private Integer isValid;
 
​
 
public Integer getId() {
 
return id;
 
}
 
​
 
public void setId(Integer id) {
 
this.id = id;
 
}
 
​
 
public String getContent() {
 
return content;
 
}
 
​
 
public void setContent(String content) {
 
this.content = content;
 
}
 
​
 
public Integer getIsValid() {
 
return isValid;
 
}
 
​
 
public void setIsValid(Integer isValid) {
 
this.isValid = isValid;
 
}
 
}
 
其中：
 
@ApiModel(description = "测试模型实体")作用在参数实体或者响应实体上，description代表描述信息；
 
@ApiModelProperty(name = "id", value = "主键", hidden = true)作用在实体属性上，标记属性名称和说明内容，name代表属性名称，value表示属性内容，hidden是否因此，默认是false。
 
修改TestController：
 
package com.mage.swagger_restful.controller;
 
​
 
import com.mage.swagger_restful.model.Test;
 
import io.swagger.annotations.Api;
 
import io.swagger.annotations.ApiImplicitParam;
 
import io.swagger.annotations.ApiOperation;
 
import io.swagger.annotations.ApiParam;
 
import org.springframework.web.bind.annotation.*;
 
​
 
@RestController
 
@RequestMapping("test")
 
@Api(tags = "测试API接口")
 
public class TestController {
 
​
 
@GetMapping("")
 
@ApiOperation(value="获取列表数据", notes="获取列表下测试数据")
 
public String list() {
 
return "查询列表数据!";
 
}
 
​
 
@GetMapping("{id}")
 
@ApiOperation(value="获取ID数据", notes="根据ID获取某条测试数据")
 
@ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)
 
public String find(@PathVariable Integer id) {
 
return String.format("根据主键查询数据: %d", id);
 
}
 
​
 
@PostMapping("")
 
@ApiOperation(value="新增数据")
 
@ApiParam(name = "test", value = "添加的测试模型实体")
 
public String add(@RequestBody Test test) {
 
return "插入数据!";
 
}
 
​
 
@PutMapping("{id}")
 
@ApiOperation(value="更新数据", notes="根据ID更新测试数据")
 
@ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)
 
public String update(@PathVariable Integer id, @ApiParam(name = "test", value = "更新的测试模型实体") @RequestBody Test test) {
 
return String.format("根据主键更新一条记录: %d", id);
 
}
 
​
 
@DeleteMapping("{id}")
 
@ApiOperation(value="删除数据", notes="根据ID删除测试数据")
 
@ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)
 
public String delete(@PathVariable Integer id) {
 
return String.format("根据主键删除记录: %d", id);
 
}
 
}
 
其中：
 
@Api(tags = "测试API接口")标记controller类是做什么的，tags表示分类；
 
@ApiOperation(value="获取列表数据", notes="获取列表下测试数据")标记controller下的方法，表示这个接口是做什么的，value就是说明作用，notes详细说明；
 
@ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)标记参数，name是参数名，value是参数说明，paramType是参数类型：path(路径参数),query(查询参数), body(请求体参数)，header(请求头参数)，form(表单提交参数)，require代表是否必填，默认是false
 
@ApiParam(name = "test", value = "更新的测试模型实体")跟@ApiImplicitParam类似，标记参数，不过不同的是：对Servlets或者非 JAX-RS的环境，只能使用 ApiImplicitParam。
 
在使用上，ApiImplicitParam比ApiParam具有更少的代码侵入性，只要写在方法上就可以了，但是需要提供具体的属性才能配合swagger ui解析使用。
 
ApiParam只需要较少的属性，与swagger ui配合更好。
 

 
点开测试API接口就可以进行测试：
 

 
8、注意
 
如果采用swagger2.9.0时，会出现一个bug，比如我修改一下TestController里面的find方法
 
旧方法：
 

 
新方法：
 

 
这时如果启动，访问swagger ui时会出现一个bug：
 

 
这个是一个数据类型转化的错误，就是因为我设置了id为int类型，而swagger默认给的是空字符串，因此就提示错误，解决方案有两种，第一种就是不要写dataType，第二种就是升级swagger-annotations和models jar包：
 
a)排除已经依赖的swagger-annotations和models jar包
 
io.springfox
 
springfox-swagger2
 
2.9.2
 
io.swagger
 
swagger-annotations
 
io.swagger
 
swagger-models
 
b) 引入新的jar包
 
io.swagger
 
swagger-annotations
 
1.5.21
 
io.swagger
 
swagger-models
 
1.5.21
 
这样也能完美解决！