背景
通常我们在服务提供交互时,经常会被要求提供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