Swagger文档转Word 文档

Swagger文档转Word 文档

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

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

1、前言

    为何会产生这个需求呢？

    咱们公司做为乙方，总是被客户追着要一份API文档，当咱们把一个 Swagger 文档地址丢给客户的时候。客户仍是很不满意，嫌不够正式！！死活坚持要一份 word 文档 。而后领导给了个接口模板，就把这个活交给我了......我去，近10个微服务，几百个接口，这不得要了个人命啊（最后整理出来将近200页的 word 文档）。最后，仍是领导有办法：要不咱们把Swagger的 json文件转成word文档吧！

    一直坚持一句话。做为使用者，人要迁就机器；做为开发者，要机器迁就人。

2、思路

     领导提供了一个接口模板，相似下面这样，其实就是一个word的table页。想到 html 能够转 word ，那么问题就变成了 ：

一、解析JSON 文件

二、把JSON文件的内容填充进html 的Table中

三、由html直接转成word

    几百个接口，一鼓作气！以下，还有一个简单的示例，就是请求参数 和 返回值 。怎么处理呢？在程序中写了 HTTP 的请求，封装了须要的参数去执行了一个请求，获得相应的返回值！

      

3、实现

一、封装对象

按照面向对象的思想，一个接口Table就是一个对象，可变的请求参数和返回参数也封装成一个对象......

 Table

 Request

 Response

二、解析 json

先来看看Swagger json文件的格式吧！须要注意的是这个 json 文件默认的 host 是没有加 http:// 前缀的，须要咱们手动加上，由于程序的HTTP请求不像浏览器同样会自动补上 http:// 的前缀 ......

    解析JSON真是一件枯燥的工做，你们能够按照本身想要生成模板的样子修改这边的代码......须要提的是，这里有一点让我纠结了很久。怎么伪造接口的请求参数发送HTTP请求以免不会抛异常呢？最后仍是参考了Swagger的方式，即：若是是 String 类型的参数，就把这个参数置为"string"；若是是 Integer 类型的参数，就把这个参数置为 0 ；若是是Double 类型的参数，就置为 0.0 ；若是是其余没办法预见的类型，就所有置为 null；

    解析 JSON 用的是Spring推荐的 jackson ，这部分感受没什么好说的，直接上代码吧！

 TableServiceImpl

三、html 模板

咱们须要一个和 Word Table 模板同样的HTML 页面，而后利用JSP的 foreach 遍历后台获得的 List<Table> 集合，一鼓作气，生成全部接口......

 json.jsp

 四、效果

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

固然，剩下的工做，就要咱们手动去整理维护了。好比：把属于同一个类的请求分类整理到一块儿；把HTTP请求错误的返回值删除（还没法适配全部的HTTP请求状况）；整理维护效果以下：

 

4、使用

    若是直接采用个人API文档模板的话，只须要将 resources 目录下的 data.json 文件的内容替换成本身的Swagger Json 文件内容就好。可是，考虑到咱们模板中的返回参数是咱们公司一个自定义的对象，因此可能这里还须要你们根据本身的要求稍做修改，主要 修改TableServiceImpl 类下的 listResponse() 方法。

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

    另外，我以为 TableServiceImpl  还有很大能够改善的地方，代码略显冗余。以后慢慢维护吧！固然，很欢迎你们一块儿来开发...哈哈

5、结语

    一直以为，IT最迷人的地方就是开源和分享，你们互不相识，即便没有利益可图，却能为同一个项目，相同的目标 贡献本身的时间和精力。想一想就难以想象。写这个博文的目地更可能是分享本身的创意和想法，说实话，代码可能写的有点烂。还请你们不要嫌弃，不吝指教！

6、更新说明

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

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

一、引入了Spring的RestTemplate取代 HttpClients 以支持更多的Restful请求。
二、命名规范以及增长异常处理，对于没法处理的HTTP请求返回空字符串。
三、修改以前导入data.josn的方式，变成restTemplate.getForObject("SwaggerJson的url地址",Map.class);的动态获取方式。

    如今的使用方式也更加简单：

一、修改resources目录下resources.properties文件的 swaggerUrl 为Swagger Json资源的url地址。 二、服务启动后：访问 http://host(主机):port(端口)/getWord，etc：http://localhost:8080/getWord  三、将生成的getWord文件，增长后缀名 getWord.doc 。