Swagger文档转Word 文档

Swagger文档转Word 文档
GitHub 地址：https://github.com/JMCuixy/SwaggerToWord

原创作品，转载请注明出处：Swagger文档转Word 文档 - JMCui - 博客园

一、前言
为什么会产生这个需求呢？

我们公司作为乙方，老是被客户追着要一份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请求方法命名（这个项目中是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 。

Swagger文档转Word 文档相关推荐

大学“电路分析基础”试题合集第六章（文末附PDF文档与Word文档）
大学"电路分析基础"试题合集第一章大学"电路分析基础"试题合集第二章大学"电路分析基础"试题合集第三章大学"电路分析基础&q ...
pdf文档编辑（pdf编辑器）、pdf文档转换为word文档（pdf转换为word转换器）——Adobe Acrobat DC软件的下载与安装
一.前言很多时候需要用到一些文档中的一些内容信息,像word这种文档是很好编辑的,可以直接复制里面的内容也可以直接对文档进行编辑,但是由于pdf文档格式美观,并能保持手机电脑文档格式一致,不乱码,所 ...
收藏夹吃灰系列(二):教小师妹通过代码实现Swagger在线接口文档转word文档！教完后...？
话不多说,工具源码直接分享给大家吧: 如果最后觉得该代码生成器对你有所帮助,请不要吝啬你的赞,直接pia的点亮就完了啦,up up up!!! 如下就是全码,拿走!不谢!!助你趁早解放双手! 本地sw ...
html在分页功能中如何实现当前页面的页码样式与其他页面不同_如何使用word文档？word文档使用技巧教程？...
Word文档使用方法与教程: 使用正确的部分和章节标题我们在前面的章节中介绍了预设样式,但是这些样式可用于快速创建章节,子标题和标题页.在"主页"功能区选项卡中找到样式,可以在其 ...
Python 技术篇 - 使用pypandoc库实现html文档转word文档实例演示
首先需要安装 pandoc 程序,pypandoc 是用来调用该程序来完成工作的. 工具获取: 小蓝枣的csdn资源仓库转换代码如下: # -*- coding:utf-8 -*- import p ...
用 Python 将微信热文转换成Word文档 | 神级操作
不得不说微信公众号已经成为了一个开放平台,每天数以万计的微信公众号文章在这产生,我们关注一个微信公众号每天便可以看到新的文章,我们同时也不知不觉的将好的文章分享到给朋友. 那么如何保存一个好的文章呢? ...
神级操作丨用 Python 将微信热文转换成Word文档
不得不说微信公众号已经成为了一个开放平台,每天数以万计的微信公众号文章在这产生,我们关注一个微信公众号每天便可以看到新的文章,我们同时也不知不觉的将好的文章分享到给朋友. 那么如何保存一个好的文章呢? ...
Word的样式库在选项卡中_如何使用word文档？word文档使用技巧教程？
Word文档使用方法与教程: 使用正确的部分和章节标题我们在前面的章节中介绍了预设样式,但是这些样式可用于快速创建章节,子标题和标题页.在"主页"功能区选项卡中找到样式,可以在其 ...
C# 打印文档（word文档）
我测试了几种打印文档的方案,第一个方案测试过程中发现打印的都是乱码,后来我发现,word文档好像不能以流的方式读取,这个还有待研究. using System; using System.Collec ...
使用Python互转pdf文档和word文档
1 前言一日,欲将手头上的一份pdf文档转换成word文档.先试着用XX办公软件试了下,微信扫码登录后,在PDF转换界面,选中文档,点击"开始转换",弹出提示对话框:免费的只给转 ...

Swagger文档转Word 文档

Swagger文档转Word 文档相关推荐

最新文章

热门文章