Swagger文档转Word

Swagger文档转Word 文档

 

GitHub 地址：https://github.com/JMCuixy/SwaggerToWord/tree/developer

原创作品，转载请注明出处：http://www.cnblogs.com/jmcui/p/8298823.html

一、前言

为什么会产生这个需求呢？

我们公司作为乙方，老是被客户追着要一份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<Table> 集合，一气呵成，生成所有接口......

 json.jsp

4、效果

把代码运行起来后，访问JSP页面，不会像平常一样看到 HTML 页面，而是直接下载生成一个 文件，按照SpringMVC请求方法命名（这个项目中是getJson文件）。把这个文件的后缀名改成 .doc 就能看到效果了！差不多是如下效果：

当然，剩下的工作，就要我们手动去整理维护了。比如：把属于同一个类的请求分类整理到一起；把HTTP请求错误的返回值删除（还无法适配所有的HTTP请求情况）；整理维护效果如下：

四、使用

如果直接采用我的API文档模板的话，只需要将 resources 目录下的 data.json 文件的内容替换成自己的Swagger Json 文件内容就好。但是，考虑到我们模板中的返回参数是我们公司一个自定义的对象，所以可能这里还需要大家根据自己的要求稍作修改，主要 修改TableServiceImpl 类下的 listResponse() 方法。

需要说明的是，这个项目还没有很好的支持所有的HTTP请求，比如 restful 服务将请求参数放在请求路径中的；比如参数是放在header中的；以及一系列可能没有考虑到的bug......

另外，我觉得 TableServiceImpl  还有很大可以改善的地方，代码略显冗余。之后慢慢维护吧！当然，很欢迎大家一起来开发...哈哈

五、结语

一直觉得，IT最迷人的地方就是开源和分享，大家互不相识，即使没有利益可图，却能为同一个项目，相同的目标 贡献自己的时间和精力。想想就不可思议。写这个博文的目地更多是分享自己的创意和想法，说实话，代码可能写的有点烂。还请大家不要嫌弃，不吝指教！