spring boot 2.x配置swagger2

spring boot 2.x项目配置swagger2步骤和问题总结

随着时代发展，前后端分离的开发的发展趋势越来越明显，对于后端人员来说，繁杂的接口文档，工作量非常复杂。经过小紫一段时间的尝试和总结，今天给大家分享一下关于spring boot 2.x配置swagger2过程中相关配置和需要注意的事项，同时提出几个小紫在开发过程中遇到的问题,欢迎小伙伴们下方留言斧正！

一项目技术构成

项目整体采用spring boot 2.1.3.RELEASE版本，通过集成swagger2,生成在线接口文档，并满足以下项目需求。

1. 生成在线接口文档，可以在线测试。
2. 自定义API分组，分为web端，移动端。
3. 在head增加参数token非全局配置。

备注：项目采用前后端分离，通过head中加入token访问认证，后台自定义注解@RequiredToken和利用aop机制对接口进行token认证判断，标识@RequiredToken注解的方法访问需要先进行登录认证。

二pom.xml依赖关系

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

备注：springfox-swagger2 生成在线api文档核心包，springfox-swagger-ui生成在线文档的页面

三Swagger2配置

这个配置类，主要配置API文档需要扫描的Controller包的路径以及非全局token认证配置，配置成功后，项目启动自动加载配置，无需进行多次配置

package com.hxss.skhb.config;
import java.util.ArrayList;
import java.util.List;
import com.google.common.base.Predicate;
import com.hxss.skhb.annotation.RequiredToken;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.google.common.base.Predicates;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.paths.AbstractPathProvider;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import static springfox.documentation.builders.PathSelectors.ant;
/**
* @ClassName: Swagger2Config  
* @Description: TODO(swagger2配置文件)  
* @author 小紫念沁
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
   
	
	/**
	 * swagger2文档开关,在生产环境下关闭在线文档
	 */
	@Value("${springfox.documentation.swagger.enable}")
	private boolean enableSwagger;
	
	
	/**
	 * swagger2文档配置获取api docs json数据的请求路径
	 */
	@Value("${springfox.documentation.swagger.v2.path}")
	private String path;
	
	
	/**
	 * swagger2文档配置host路径
	 */
	@Value("${springfox.documentation.swagger.v2.host}")
	private String host;


	/**
	 * web端需要token验证接口
	 * @return
	 */
	@Bean
    public Docket createRestWebApiRequiredToken() {
   

		return new Docket(
        		//选择文档版本类型及文档类型
        		DocumentationType.SWAGGER_2)
        		//分组名称
        		.groupName("web端需要token验证接口")
        		//日期格式转换
        		.directModelSubstitute(org.joda.time.LocalDate.class, java.sql.Date.class)
                .directModelSubstitute(org.joda.time.DateTime.class, java.util.Date.class)
                //配置获取api docs json数据的请求路径
        		.pathProvider(new GtPaths())
        		//#请求的根路径
        		.host(host)
        		//自定义head参数名
        		.securitySchemes(securitySchemes())
        		//自定义head参数值
                .securityContexts(securityContexts