Swagger API在线文档框架应用

本教程版本使用2.9.2

1、导入maven依赖

<!-- swagger -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
        <exclusions>
        	<exclusion>
           		<groupId>io.swagger</groupId>
            	<artifactId>swagger-models</artifactId>
        	</exclusion>
    	</exclusions>
    </dependency>
    <dependency>
    	<groupId>io.swagger</groupId>
    	<artifactId>swagger-models</artifactId>
    	<version>1.5.21</version>
	</dependency>
    <!-- swagger-ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
    	<groupId>com.github.xiaoymin</groupId>
    	<artifactId>swagger-bootstrap-ui</artifactId>
    	<version>1.8.5</version>
	</dependency>

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<Parameter> pars = new ArrayList<Parameter>();
        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<Role> roleList(@RequestBody Role role) {
		List<Role> 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<Parameter> pars = new ArrayList<Parameter>();
        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包即可解决，具体依赖如下（标红部分注意）：

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
        <exclusions>
            <exclusion>
                   <groupId>io.swagger</groupId>
                <artifactId>swagger-models</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.5.21</version>
    </dependency>