背景
通常我们在服务提供交互时,经常会被要求提供api文档,各种情况和格式要求都会有,如pdf,showdoc,word以及html等。其中做甲方项目的苦力面对最多的就是我们今天的目的格式word。swagger2有很多现成的可以支持的(可不可用需要自己测试),但是我为了偷懒文档生成,直接使用了最新的swagger3,接下来就是我不断折腾找工具,改工具的过程记录和最后的缝合怪。
折腾
经过搜索后找到一个不能用的swagger2word,而且只支持swagger2。看了几眼,改造成本过大,放弃。
然后找到官方维护的swagger-parser,这个倒是支持swagger3,但是这个有一个问题就是需要自己去写模版来套对象做输出(心累,收藏夹里吃灰吧)。
那么最后瞄准一个已经遗弃的项目swagger2markup,作者没有太多的精力去维护,但是本身功能完善,文档详尽,但是!它不支持swagger3。而且它支持的格式为ASCIIDOC,MARKDOWN。但是我有神器Typora啊(这篇文章也是用这个编辑器写的)。支持导出为pdf、html、word。所以决定用它了。
本想通过引入新版本的swagger-parser,让其直接支持swagger3的openapi spec 不,我不想,太累人了。
最后思路变为:
swagger3生成json->想办法将其转化为swagger2->使用swagger2markup生成markdown->Typora将markdown转化为word->完美Over