将Swagger2文档导出为HTML或markdown等格式离线阅读
文章图片
将Swagger2文档导出为HTML或markdown等格式离线阅读
网上有很多《使用swagger2构建API文档》的文章,swagger2文档是一个在线文档,需要使用HTTP访问。但是在我们日常使用swagger接口文档的时候,有的时候需要接口文档离线访问,如将文档导出为html、markdown格式。又或者我们不希望应用系统与swagger接口文档使用同一个服务,而是导出HTML之后单独部署,这样做保证了对接口文档的访问不影响业务系统,也一定程度提高了接口文档的安全性。核心的实现过程就是:
- 在swagger2接口文档所在的应用内,利用swagger2markup将接口文档导出为adoc文件,也可以导出markdown文件。
- 然后将adoc文件转换为静态的html格式,可以将html发布到nginx或者其他的web应用容器,提供访问(本文不会讲html静态部署,只讲HTML导出)。
注意:adoc是一种文件格式,不是我的笔误。不是doc文件也不是docx文件。一、maven依赖类库 在已经集成了swagger2的应用内,通过maven坐标引入相关依赖类库,pom.xml代码如下:
文章图片
【将Swagger2文档导出为HTML或markdown等格式离线阅读】
swagger2markup用于将swagger2在线接口文档导出为html,markdown,adoc等格式文档,用于静态部署或离线阅读。其中第一个maven坐标是必须的。后两个maven坐标,当你在执行后面的代码过程中报下图中的ERROR,或者有的类无法import的时候使用。
文章图片
swagger2markup过程可能抛出的异常
产生异常的原因已经有人在github的issues上给出解释了:当你使用swagger-core版本大于等于1.5.11,并且swagger-models版本小于1.5.11就会有异常发生。所以我们显式的引入这两个jar,替换掉swagger2默认引入的这两个jar。
文章图片
swagger2markup异常的解决方案
二、生成adoc格式文件 下面的代码是通过编码方式实现的生成adoc格式文件的方式
文章图片
- 使用RunWith注解和SpringBootTest注解,启动应用服务容器。 SpringBootTest.WebEnvironment.DEFINED_PORT表示使用application.yml定义的端口,而不是随机使用一个端口进行测试,这很重要。
- Swagger2MarkupConfig 是输出文件的配置,如文件的格式和文件中的自然语言等
- Swagger2MarkupConverter的from表示哪一个HTTP服务作为资源导出的源头(JSON格式),可以自己访问试一下这个链接。8888是我的服务端口,需要根据你自己的应用配置修改。
- toFile表示将导出文件存放的位置,不用加后缀名。也可以使用toFolder表示文件导出存放的路径。二者区别在于使用toFolder导出为文件目录下按标签TAGS分类的多个文件,使用toFile是导出一个文件(toFolder多个文件的合集)。
文章图片
上面的这一段代码是生成markdown格式接口文件的代码。执行上面的2段单元测试代码,就可以生产对应格式的接口文件。
还有一种方式是通过maven插件的方式,生成adoc和markdown格式的接口文件。笔者不常使用这种方式,没有使用代码生成的方式配置灵活,很多配置都放到pom.xml感觉很臃肿。但还是介绍一下,首先配置maven插件swagger2markup-maven-plugin。
文章图片
然后运行插件swagger2markup就可以了,如下图:
文章图片
插件运行方式(点击可放大)
三、通过maven插件生成HTML文档
文章图片
adoc的sourceDirectory路径必须和第三小节中生成的adoc文件路径一致。然后按照下图方式运行插件。
文章图片
asciidoctor:process-asciidoc插件运行
HTMl接口文档显示的效果如下,有了HTML接口文档你想转成其他各种格式的文档就太方便了,有很多工具可以使用。这里就不一一介绍了。
文章图片
推荐:SpringBoot系列精品文章(16章97节), http://springboot.zimug.com
本号只做持续的知识输出,希望您能关注、评论、转发!您的支持是我不竭的创作动力!让知识产生价值、让程序员改变世界!
推荐阅读
- 即将到手三百万
- 思友人
- 20210307《挑战赛怂人胆》【能量将帅挑战赛(01)】
- ts泛型使用举例
- 苍灵十二将I|苍灵十二将I 第一百二十五章 关门猎兽
- 那条灰色的人行道
- 《没有你我将会很幸福》
- 《将来的你,一定会感谢现在战胜烦恼的自己-------第四章/第十一节/用逆向思维解除烦恼》
- 牧人将归
- 首届中国苏州江南文化艺术国际旅游节将于8月24日启幕