以前一直维护wiki,不是用测试用例就是用postman工具,偶然的机会相遇了swagger,感受非常试用。因此决定将其配置流程乃至中间遇到的坑记录下来。php
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。整体目标是使客户端和文件系统做为服务器以一样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,容许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。html
maven依赖java
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.9.6</version> </dependency>
swagger 配置类web
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.openplatform.api.controller")) .paths(PathSelectors.any()) .build() .globalOperationParameters(pars) .apiInfo(apiInfo()); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("街云相关接口测试") .description("以下连接是直接跳转到wiki的,方便快捷") .contact(new Contact("wiki address", "http://192.168.31.215:9999/dokuwiki/doku.php?id=start", "")) .license("") .licenseUrl("") .version("1.0.0") .build(); } }
一、由于swagger是页面化的,因此最基本的则是集成其本身的html页面以及其样式包
页面错误展现:{“code”:404,“data”:{},“msg”:“Not Found”,“status”:false}
代码错误:
未集成html的错误spring
2018-12-04 17:23:06.444|WARN ||o.s.w.s.PageNotFound|No mapping found for HTTP request with URI [/swagger-ui.html] in DispatcherServlet with name 'dispatcherServlet' 2018-12-04 17:23:06.500|ERROR||c.o.a.w.ErrorInfoBuilder|api error /swagger-ui.html headers={Accept=text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8, Cache-Control=max-age=0, Upgrade-Insecure-Requests=1, User-Agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36, Connection=keep-alive, If-Modified-Since=Mon, 15 Jan 2018 08:59:31 GMT, Host=127.0.0.1:8181, Accept-Language=zh-CN,zh;q=0.9,en;q=0.8, Accept-Encoding=gzip, deflate, br} java.lang.Exception: Not Found at com.openplatform.api.web.ErrorInfoBuilder.getError(ErrorInfoBuilder.java:133)
未集成其样式致使的api
2018-12-04 17:16:35.081|WARN ||o.s.w.s.PageNotFound|No mapping found for HTTP request with URI [/webjars/springfox-swagger-ui/springfox.js] in DispatcherServlet with name 'dispatcherServlet' 2018-12-04 17:16:35.082|ERROR||c.o.a.w.ErrorInfoBuilder|api error /webjars/springfox-swagger-ui/springfox.js headers={Accept=*/*, Connection=keep-alive, User-Agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36, Referer=http://127.0.0.1:8181/swagger-ui.html, Host=127.0.0.1:8181, Accept-Language=zh-CN,zh;q=0.9,en;q=0.8, Accept-Encoding=gzip, deflate, br} java.lang.Exception: Not Found
解决办法:服务器
@Override public void addResourceHandlers(ResourceHandlerRegistry registry) { //swagger静态页面和样式加载 registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); }
二、版本冲突app
Caused by: java.lang.NoSuchMethodError: com.google.common.collect.FluentIterable.concat(Ljava/lang/Iterable;Ljava/lang/Iterable;)Lcom/google/common/collect/FluentIterable; at springfox.documentation.schema.DefaultModelDependencyProvider.dependentModels(DefaultModelDependencyProvider.java:79)
报如上错误,则确定是版本不兼容,简单的办法则是经过看相互依赖找到问题,或者直接修改成统一版本,问题则迎刃而解。
注:swagger 2.7.0确实有不少问题,你们能够略过这个版本。框架
对于Restful风格的接口,身份信息都是放在请求头中,经过拦截器来读取Header中的Token信息进行身份验证,可是咱们在Swagger中怎么设置请求头参数,咱们须要在每个方法的中都加一个Header参数吗?固然不是。Swagger中的ParameterBuilder能够为咱们全部的接口文档加上Token参数。想加几个验证参数限制均可以。
修改swaggerConfig的方法,添加token参数:maven
@Bean public Docket createRestApi() { //token和APPID参数传入配置 List<Parameter> pars = new ArrayList<>(); ParameterBuilder tokenPar = new ParameterBuilder(); //参数名称 tokenPar.name("Authorization") //参数默认值 .defaultValue("") //参数描述 .description("令牌") //类型 .modelRef(new ModelRef("string")).parameterType("header").required(false).build(); ParameterBuilder appIdPar = new ParameterBuilder(); appIdPar.name("x-app-id") .defaultValue("10001") .description("appID") .modelRef(new ModelRef("string")).parameterType("header").required(false).build(); pars.add(tokenPar.build()); pars.add(appIdPar.build()); return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.openplatform.api.controller")) .paths(PathSelectors.any()) .build() .globalOperationParameters(pars) .apiInfo(apiInfo()); }
五 swagger页面样式
样式的展现和swagger的版本有直接关系,个人版本是2.8.0,因此以下的页面样式是2.8.0版本的效果。
token机制部分截图:
默认都是没必要传的,是否须要传入参数是经过项目拦截断定的。
以上几点就是腿swagger配置的基本流程以及一点心得,swagger的出现非常方便了咱们测试环境的使用,可是对于生产环境而言,确是一种危险。因此下篇则主要介绍生产环境如何禁用swagger。