Swagger文档转Word 文档（转载）

转载：http://www.cnblogs.com/jmcui/p/8298823.html

 

 

阅读目录

• 一、前言
• 二、思路
• 三、实现
• 四、使用
• 五、结语
• 六、更新说明

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

原创作品，转载请注明出处：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请求方法命名（这个项目中是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);的动态获取方式。

   

    2019-06-12 整理发布了 1.3 版本，更新说明如下：  

1、Spring 框架向 SpringBoot 升级

2、thymeleaf 取代 jsp模板 

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

1、修改 application.yml 文件的 swagger.url 为Swagger Json资源的url地址。

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

3、可以看到网页上生成的类似 word 文档的页面，右键另存为 xxx.doc 文件即可。

   

    2019-08-02 整理发布了 1.4 版本，更新说明如下：  

1、取消 HttpClient 的请求方式去获得返回值，改由从 Swagger Json 文件中直接读取

2、针对 application/json 请求方式的入参做渲染 

3、对于文字过多导致 HTML table 变形做适配

4、真诚感谢 fpzhan 的代码贡献 

   

    2019-12-18 整理发布了 1.5 版本，更新说明如下：  

1. 代码梳理和页面美化。
2. 真诚感谢 kevin4j 的代码贡献。