Swagger文档转Word 文档

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

原创作品，转载请注明出处：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

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请求方法命名（这个项目中是getWord文件）。把这个文件的后缀名改成 .doc 就能看到效果了！差不多是如下效果：

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

四、使用

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

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

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

五、结语

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

六、更新说明

    之前看《Spring In Action》的时候，发现了 RestTemplate 这个东西， 作为取代 HttpClients 的请求方式。当时就在想，要是放在这个项目中不是恰到好处？

    2018-06-21 整理发布了 1.2 版本，更新说明如下：

1、引入了Spring的RestTemplate取代 HttpClients 以支持更多的Restful请求。

2、命名规范以及增加异常处理，对于无法处理的HTTP请求返回空字符串。

3、修改之前导入data.josn的方式，变成restTemplate.getForObject("SwaggerJson的url地址",Map.class);的动态获取方式。

    现在的使用方式也更加简单：

1、修改resources目录下resources.properties文件的 swaggerUrl 为Swagger Json资源的url地址。

2、服务启动后：访问 http://host(主机):port(端口)/getWord，etc：http://localhost:8080/getWord

3、将生成的getWord文件，增加后缀名 getWord.doc 。