springboot整合swagger。完爆前后端调试

web接口开发时在调试阶段最麻烦的就是参数调试，前端需要咨询后端。后端有时候自己也不是很了解。这时候就会造成调试一次接口就需要看一次代码。Swagger帮我们解决对接的麻烦

springboot接入swagger

springboot 引入swagger只需要引入jar包，然后配置swagger启动。并配合swagger的注解使用就可以实现文档自动生成了。我们先来看看效果

环境准备

代码还是基于spring仓库开发。分支为feature/0004/springboot-swagger

swagger.version=2.9.2

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${swagger.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${swagger.version}</version> </dependency> 配置 @Configuration @EnableSwagger2 public class SwaggerConfig2 { @Bean public Docket createRestApi() { // 添加请求参数，我们这里把token作为请求头部参数传入后端 ParameterBuilder parameterBuilder = new ParameterBuilder(); List<Parameter> parameters = new ArrayList<Parameter>(); parameterBuilder.name("token").description("令牌") .modelRef(new ModelRef("string")).parameterType("header").required(false).build(); parameters.add(parameterBuilder.build()); return new Docket(DocumentationType.SWAGGER_2) .pathMapping("http://www.likecs.com/") .select() .apis(RequestHandlerSelectors.basePackage("com")) .paths(Predicates.not(PathSelectors.regex("/error.*"))) .build().apiInfo(new ApiInfoBuilder() .title("后端服务说明") .description("SpringBoot整合Swagger，详细信息......") .version("1.0") .contact(new Contact("zxhtom", "zxhtom.blog.csdn.net", "870775401@qq.com")) .license("The Apache License") .licenseUrl("http://zxhtom.gitee.io") .build()) .useDefaultResponseMessages(false) .securitySchemes(securitySchemes()) .securityContexts(securityContexts()) .globalOperationParameters(parameters); } private List<ApiKey> securitySchemes() { List<ApiKey> apiKeyList = new ArrayList(); apiKeyList.add(new ApiKey("Authorization", "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("Authorization", authorizationScopes)); return securityReferences; } } 添加请求头 securitySchemes(securitySchemes()) securityContexts(securityContexts())

在上面的两端配置就是加入全局的token设置的。在swagger-ui界面显示是右上角有一把锁的标志

接口使用

注解使用 注解 功能
@Api()   用在请求的类上。表示该类的请求类用于文档标注  
@ApiOperation()   用于方法上。对一个http请求的具体说明，出参入参说明  
@ApiModel()   对请求实体的一个说明  
@ApiModelProperty   对实体内属性说明，也可以设置默认值  
@ApiImpliciParams()   用于请求的方法上，里面是ApiImpliciParam数组  
@ApiImpliciParam()   表示单独请求参数。可以设置form表单中参数单独设置  
@ApiParam()   对请求方法中参数的单独设置 类似ApiImpliciParam  
@ApiResponses()   对请求方法上根据响应码设置说明  
@ApiResponse   单个响应码说明  
@ApiIgnore()   对该请求的忽略  

具体使用可以查看源码。源码上面有给出。

自定义swaggerUI

这里需要首先介绍下spring资源的加载顺序。

src/main/resources/META-INF/resources
src/main/resources/static
src/main/resources/public