新手入门教你轻松为springboot项目搭建swagger2
springboot项目整合swagger配置文件
本次使用的事swagger2.9.2版本，但是相对于2.8.2版本的，会存在一些问题，下面再详细说明
1，第一步，导入依赖包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
</exclusion>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.21</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>
注明：可能会有大兄弟发现，其他博客搜索到的依赖，只需要加两段就行了，为什么这里要加这么多，那是因为2.9.2版本的swagger在项目跑起来后会报下面的错误：
java.lang.NumberFormatException: For input string: “”
at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65) ~[na:1.8.0_181]
at java.lang.Long.parseLong(Long.java:601) ~[na:1.8.0_181]
at java.lang.Long.valueOf(Long.java:803) ~[na:1.8.0_181]
at io.swagger.models.parameters.AbstractSerializableParameter.getExample(AbstractSerializableParameter.java:412) ~[swagger-models-1.5.20.jar:1.5.20]
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[na:1.8.0_181]
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) ~[na:1.8.0_181]
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) ~[na:1.8.0_181]
at java.lang.reflect.Method.invoke(Method.java:498) ~[na:1.8.0_181]
所以，通过排除springfox-swagger2 引入的swagger-annotations、swagger-models 1.5.20版本，手动引入1.5.21版本的jar就可以解决这个问题。
2，项目中自建一个java配置文件的包，新增SwaagerConfig.java文件
package net.mrd.framework.config;
import java.util.ArrayList;
import java.util.List;
import org.springframework.beans.factory.annotation.Value;
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.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
- 主要是添加注解@EnableSwagger2和定义Docket的bean类。
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
// 是否开启swagger，正式环境一般是需要关闭的，可根据Springboot的多环境配置进行设置
@Value(value = "${swagger.enabled}")
Boolean swaggerEnabled;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// 是否开启
.enable(swaggerEnabled).select()
// 扫描的路径包
.apis(RequestHandlerSelectors.basePackage("net.mrd.controller"))
// 指定路径处理PathSelectors.any()代表所有的路径
.paths(PathSelectors.any()).build().pathMapping("/");
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("SpringBoot-Swagger2集成")
.description("myriadiot | migua")
.version("2.9.2").build();
}
}
3，配置完这些，就可以去访问swagger的页面了 http://localhost:8000/swagger-ui.html#/ ,如下图
4，如果你发现访问接口需要绕过 token验证，swagger2也有一个很简单的配置
只需要在SwaggerConfig.java文件中，加上下面的配置即可，（对照着看上面的配置文件加了那些内容）
package net.mrd.framework.config;
import java.util.ArrayList;
import java.util.List;
import org.springframework.beans.factory.annotation.Value;
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.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
- 主要是添加注解@EnableSwagger2和定义Docket的bean类。
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
// 是否开启swagger，正式环境一般是需要关闭的，可根据Springboot的多环境配置进行设置
@Value(value = "${swagger.enabled}")
Boolean swaggerEnabled;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// 是否开启
.enable(swaggerEnabled).select()
// 扫描的路径包
.apis(RequestHandlerSelectors.basePackage("net.mrd.controller"))
// 指定路径处理PathSelectors.any()代表所有的路径
.paths(PathSelectors.any()).build().pathMapping("/").securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("SpringBoot-Swagger2集成").description("myriadiot | migua")
.version("2.9.2").build();
}
private List<ApiKey> securitySchemes() {
List<ApiKey> apiKeyList = new ArrayList();
apiKeyList.add(new ApiKey("token", "token", "header"));
return apiKeyList;
}
// 过滤掉某些不需要token验证的接口（可有可无）
private List securityContexts() {
List 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;
}
}
加上以上配置之后，页面上会多一个锁标志
5，使用方法，登录之后获取到token，手动复制粘贴到下面的框框里，点Authorize即可
6，最后一点，如果发现把token复制到那个框框里发现没起作用的时候，检查下面两个方法 apiKeyList.add(new ApiKey(“token”, “token”, “header”));里的第一个参数token 和 securityReferences.add(new SecurityReference(“token”, authorizationScopes));方法的第一个参数是否名字一致即可
private List securitySchemes() {
List apiKeyList = new ArrayList();
apiKeyList.add(new ApiKey(“token”, “token”, “header”));
return apiKeyList;
}
List defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope(“global”, “accessEverything”);
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference(“token”, authorizationScopes));
return securityReferences;
}
7.最后，在springboot的application.properties配置文件中加上swagger.enabled=true ，这个为swagger的开关，部署到正式服的时候，不需要使用swagger，设置成false即可
完结。
以上均是本人在公司项目中实战用到，测试均无问题，后续有时间会再更新swagger2的注解使用方法。敬请关注！