码迷,mamicode.com
首页 > 其他好文 > 详细

Swagger文档转Word

时间:2018-01-18 17:17:20      阅读:1061      评论:0      收藏:0      [点我收藏+]

标签:面向   这不   lap   ima   处理   spring   面向对象的思想   int   参考   

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

Swagger文档转Word

标签:面向   这不   lap   ima   处理   spring   面向对象的思想   int   参考   

原文地址:https://www.cnblogs.com/Leo_wl/p/8310279.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
分享档案
周排行
mamicode.com排行更多图片
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!