swagger-2.6.0 记录一个下午的无聊举动

记录下今天一下午干的一个无聊但是收获还挺大的事情。
今天随意看了下项目中用到的swagger ui功能。 希望对他有点更深的了解。于是有了今天干了这些无聊的事情。
首先,springBoot集成swagger ui。
这个很简单。 三步就行了。这个也不是今天的重点,随便看看。
1、pom.xml中添加依赖

io.springfox
springfox-swagger2
2.6.0


io.springfox
springfox-swagger-ui
2.6.0

2、增加配置的Bean
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(“com.myapp”))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(“Spring Boot中使用Swagger2构建RESTful APIs”)
.description(“myapp”)
.termsOfServiceUrl(“http://www.myapp.com/“)
.contact(“roykingw”)
.version(“1.0”)
.build();
}
}
3、然后就可以在controller里面添加注释
@ApiOperation(value = “测试接口”, notes = “增加实体接口”)
@RequestMapping(value = “/addObject”, method = RequestMethod.POST)
public Object addObject(@RequestBody String requestMessage, HttpServletRequest request) {
。。。。。
}
这之类的。然后启动应用就能访问 swagger-ui.html看到生成出来的接口报文了。

然后开始了今天一天的时间挥霍。
随意在百度上搜索了一下关于swagger ui的消息,后来确定下了两个关注的问题:
1、swagger-ui 支持多语言版本, 但是默认生成的全都是英文的。于是也就冒出了第二个想法,怎么把他的多语言功能用上。
2、swagger-ui页面实际上是调用几个swagger的rest接口最后组成的页面;
比如 可以访问 /v2/api-docs 获取接口配置信息。
访问 /swagger-resources/configuration/ui 获取页面UI配置信息。
于是就冒出了第一个想法, 这个UI配置信息,既然是配置化的,那要怎么去干预配置呢?

然后从第一个问题开始。
一开始,信心十足,觉得随意度娘一会就能解决。 搜了几个小时,结果相当失望。度娘上一大堆抄来抄去的文章,大都只涉及到怎么把swagger ui用上。然后就没事了。稍微深入一点点的也就说到/v2/api-docs路径地址能进行配置。 然而我的这个小问题,还真真的找不到答案。于是决定自己来。
首先,页面既然能访问,肯定是有html的。在哪里呢?当然还是从jar包入手。新建了一个工程,只引入了swagger ui的依赖。然后去maven依赖库里一个一个jar包去找。 找了一会,很快就发现了目标。

swagger-2.6.0 记录一个下午的无聊举动_第1张图片

这不就是访问的压面吗。 既然地方找到了,那后面的事情就很容易了。
打开页面,html js一个个的看。 看了会,只有一个感觉,这代码看着真的是舒服。然而,字体翻译的地方呢? 没找到啊。但是结合页面,发现了一点,swagger-ui页面上的多语言翻译是怎么做到的?就是把所有要翻译的字符放到带有 data-sw-translate 属性的div 里。
swagger-2.6.0 记录一个下午的无聊举动_第2张图片
而是怎么实现翻译的? 还是没有找到。 就在突然没了主意的时候,随意的鼠标一点,点到了lang文件夹,于是,谜底揭开了。
swagger-2.6.0 记录一个下午的无聊举动_第3张图片
原来全在这里面呢。打开一看,translator.js里负责了翻译。而zh-cn.js这些语言的js中负责了translator的多语言学习。一目了然。
到这里,就了解到了目前这个版本的地方。其实所有的翻译就在包里。swagger-ui.html只要增加引入translator.js和zh-ch.js,就可以完成中文化翻译了。
于是,后面的尝试就很简单了。 分析了一下,由于swagger-ui是打在jar包里的, 要去修改,肯定不可能。于是想到最后做个页面,把swaagger-ui.html 页面load进来。但是springfox.js里的baseurl方法又限定了访问的路径,必须是/swagger-ui.html否则会报错。
swagger-2.6.0 记录一个下午的无聊举动_第4张图片
那就干脆自己做个页面好了。把 swagger-ui.html复制出来,把springfox.js换成另外一个js,把这个访问路径改一改,于是,中文就出来了。
swagger-2.6.0 记录一个下午的无聊举动_第5张图片

而有了这个经验,第二个问题就很顺手就找到了。几个jar包随意翻一下,很快找到了目标
swagger-2.6.0 记录一个下午的无聊举动_第6张图片

反编译出来,看结果
swagger-2.6.0 记录一个下午的无聊举动_第7张图片

安全配置 与 UI配置 就在这。只要在swagger2.java里往spring容器里注入这两个Bean,那注入的配置就会覆盖默认的配置。

其实是一个下午的无聊之做。但是确实有很大的收获。
首先,越是好的东西,越不要浅尝辄止,用完就成。深入研究,也不要打算一鼓作气,经常随意的翻一翻,可能就会有意外的收获。而且,度娘很强大,但不要太依赖度娘,也还是要自己动动手才能算好,像今天一下午,其实花费时间最多的也就在度娘上,自己动手,反而进度很快。
其次,找准问题,看代码就不会那么无聊了。因为swagger ui基于注释收集接口信息的方式,项目中已经以用到,虽然封装,应用肯定不一样,但是技术差不多,就没有过多关注,分散注意力。
然后,看看代码如何组织,也是相当有收获。基于注释的开发方式,项目中也有用到,甚至应用场景比这个swagger ui的只有更加复杂。但是,要说代码清晰易懂,组织分明,那就真的看出了差距。

当然,这只是一个开始,真正springfox和swagger的核心东西都还没有接触呢。 以后有时间继续深入吧。

你可能感兴趣的:(SpringBoot)