Swagger API在线文档框架应用

本教程版本使用2.9.2

1、导入maven依赖

    
        io.springfox
        springfox-swagger2
        2.9.2
        
        	
           		io.swagger
            	swagger-models
        	
    	
    
    
    	io.swagger
    	swagger-models
    	1.5.21
	
    
    
        io.springfox
        springfox-swagger-ui
        2.9.2
    
    
    	com.github.xiaoymin
    	swagger-bootstrap-ui
    	1.8.5
	

2、SwaggerConfig设置

import java.util.ArrayList;
import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

import io.swagger.annotations.ApiOperation;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurerAdapter{
	@Bean
    public Docket swaggerSpringMvcPlugin() {
		//添加head参数start
		ParameterBuilder ticketPar = new ParameterBuilder();
        List pars = new ArrayList();
        ticketPar.name("token").description("token")
                .modelRef(new ModelRef("String")).parameterType("header")
                .required(false).build(); 
        pars.add(ticketPar.build()); 
        //添加head参数end

        return new Docket(DocumentationType.SWAGGER_2)
        		.apiInfo(apiInfo())
        		.select()
        		.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
        		.apis(RequestHandlerSelectors.basePackage("com.enw"))
        		.build().globalOperationParameters(pars);
    }
	private ApiInfo apiInfo(){
	      return new ApiInfoBuilder()
	            .title("API接口文档")
	            .description("CRM管理系统API接口文档")
	            .contact(new Contact("", "", ""))
	            .version("1.0")
	            .build();
	   }

}

3、具体使用

@Api(tags="角色控制器")
@RestController
@RequestMapping("/role/")
public class RoleController extends BaseController {

	@Autowired
	private RoleService roleService;


	@SuppressWarnings("unchecked")
	@ApiOperation(value = "获取角色列表" ,  notes="获取角色列表")
	@ApiImplicitParam(name = "role", value = "角色信息", required = false, dataType = "Role")
	@PostMapping("list")
	@UserLoginToken
	public JsonResult roleList(@RequestBody Role role) {
		List list = this.roleService.findAllRole(role);
		return JsonResult.success(list);
	}
}

 4、访问 localhost:端口号/doc.html  效果如下：

注意：

1、如果有拦截器需要放开的路径：

"doc.html","/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**"

2、一般前后端分离，前端的token都是封装到请求头header中的，设置统一请求头token

        //添加head参数start
		ParameterBuilder ticketPar = new ParameterBuilder();
        List pars = new ArrayList();
        ticketPar.name("token").description("token")
                .modelRef(new ModelRef("String")).parameterType("header")
                .required(false).build(); 
        pars.add(ticketPar.build()); 
        //添加head参数end

3、今天使用doc.html访问时后台报错:java.lang.NumberFormatException: For input string: "".原因是：

由于我pom引入的io.springfox:springfox-swagger-ui:2.9.2版本的jar包内置为io.swagger:swagger-models包为1.5.20版本。1.5.20版本中判断example只判断是否为null,没有判断example为空字符串""的情况所以报错.1.5.21版本新增了判断example是否为null和"".

解决办法：所以排除1.5.20包重新导入1.5.21包即可解决，具体依赖如下（标红部分注意）：

        io.springfox
        springfox-swagger2
        2.9.2
       
            
                   io.swagger
                swagger-models
            
        
   
   
        io.swagger
        swagger-models
        1.5.21