GitHub 地址: https://github.com/JMCuixy/SwaggerToWord/tree/developer
一,前言
为什么会产生这个需求呢?
我们公司作为乙方,老是被客户追着要一份 API 文档,当我们把一个 Swagger 文档地址丢给客户的时候.客户还是很不满意,嫌不够正式!!死活坚持要一份 word 文档 .然后领导给了个接口模板,就把这个活交给我了...... 我去,近 10 个微服务,几百个接口,这不得要了我的命啊(最后整理出来将近 200 页的 word 文档).最后,还是领导有办法:要不我们把 Swagger 的 json 文件转成 word 文档吧!
一直坚持一句话.作为使用者,人要迁就机器;作为开发者,要机器迁就人.
二,思路
领导提供了一个接口模板,类似下面这样,其实就是一个 word 的 table 页.想到 html 可以转 word ,那么问题就变成了 :
1,解析 JSON 文件
2,把 JSON 文件的内容填充进 html 的 Table 中
3,由 html 直接转成 word
几百个接口,一气呵成!如下,还有一个简单的示例,就是请求参数 和 返回值 .怎么处理呢?在程序中写了 HTTP 的请求,封装了需要的参数去执行了一个请求,得到相应的返回值!
三,实现
1,封装对象
按照面向对象的思想,一个接口 Table 就是一个对象,可变的请求参数和返回参数也封装成一个对象......
Table
Request
Response
2,解析 json
先来看看 Swagger json 文件的格式吧!需要注意的是这个 json 文件默认的 host 是没有加 http:// 前缀的,需要我们手动加上,因为程序的 HTTP 请求不像浏览器一样会自动补上 http:// 的前缀 ......
解析 JSON 真是一件枯燥的工作,大家可以按照自己想要生成模板的样子修改这边的代码...... 需要提的是,这里有一点让我纠结了好久.怎么伪造接口的请求参数发送 HTTP 请求以避免不会抛异常呢?最后还是参考了 Swagger 的方式,即:如果是 String 类型的参数,就把这个参数置为 "string";如果是 Integer 类型的参数,就把这个参数置为 0 ;如果是 Double 类型的参数,就置为 0.0 ;如果是其他没办法预见的类型,就全部置为 null;
解析 JSON 用的是 Spring 推荐的 jackson ,这部分感觉没什么好说的,直接上代码吧!
TableServiceImpl
3,html 模板
我们需要一个和 Word Table 模板一样的 HTML 页面,然后利用 JSP 的 foreach 遍历后台得到的 List
集合,一气呵成,生成所有接口......
json.jsp
4,效果
把代码运行起来后,访问 JSP 页面,不会像平常一样看到 HTML 页面,而是直接下载生成一个 文件,按照 SpringMVC 请求方法命名(这个项目中是 getJson 文件).把这个文件的后缀名改成 .doc 就能看到效果了!差不多是如下效果:
当然,剩下的工作,就要我们手动去整理维护了.比如:把属于同一个类的请求分类整理到一起;把 HTTP 请求错误的返回值删除(还无法适配所有的 HTTP 请求情况);整理维护效果如下:
四,使用
如果直接采用我的 API 文档模板的话,只需要将 resources 目录下的 data.json 文件的内容替换成自己的 Swagger Json 文件内容就好.但是,考虑到我们模板中的返回参数是我们公司一个自定义的对象,所以可能这里还需要大家根据自己的要求稍作修改,主要 修改 TableServiceImpl 类下的 listResponse() 方法.
需要说明的是,这个项目还没有很好的支持所有的 HTTP 请求,比如 restful 服务将请求参数放在请求路径中的;比如参数是放在 header 中的;以及一系列可能没有考虑到的 bug......
另外,我觉得 TableServiceImpl 还有很大可以改善的地方,代码略显冗余.之后慢慢维护吧!当然,很欢迎大家一起来开发... 哈哈
五,结语
一直觉得,IT 最迷人的地方就是开源和分享,大家互不相识,即使没有利益可图,却能为同一个项目,相同的目标 贡献自己的时间和精力.想想就不可思议.写这个博文的目地更多是分享自己的创意和想法,说实话,代码可能写的有点烂.还请大家不要嫌弃,不吝指教!
来源: https://www.cnblogs.com/jmcui/p/8298823.html