将Swagger2文档导出为HTML或减价等格式离线阅读解析

网上有很多《使用swagger2构建API文档》的文章,该文档是一个在线文档,需要使用HTTP访问。但是在我们日常使用的接口文档的时候,有的时候需要接口文档离线访问,如将文档导出为html,减价格式。又或者我们不希望应用系统与大摇大摆接口文档使用同一个服务,而是导出html之后单独部署,这样做保证了对接口文档的访问不影响业务系统,也一定程度提高了接口文档的安全性。核心的实现过程就是:

　　<李>在swagger2接口文档所在的应用内,利用swagger2markup将接口文档导出为adoc文一起件,也可以导出减价文件。 　　<李>然后将adoc文一起件转换为静态的html格式,可以将html发布到nginx或者其他的网络应用容器,提供访问(本文不会讲html静态部署,只讲html导出)。 　　

　　

注意:adoc是一起一种文件格式,不是我的笔误。不是医生文件也不是多克斯文件。

　　 　　

　　

在已经集成了swagger2的应用内,通过maven坐标引入相关依赖类库,pom.xml代码如下:

　　 　　 　　& lt; dependency> 　　& lt; groupId> io.github.swagger2markup 　　& lt; artifactId> swagger2markup 　　& lt; version> 1.3.1 　　& lt;/dependency> 　　& lt; dependency> 　　& lt; groupId> io.swagger 　　& lt; artifactId> swagger-core 　　& lt; version> 1.5.16 　　& lt;/dependency> 　　& lt; dependency> 　　& lt; groupId> io.swagger 　　& lt; artifactId> swagger-models 　　& lt; version> 1.5.16 　　& lt;/dependency> 　　 　　

swagger2markup用于将swagger2在线接口文档导出为html,减价,adoc等一起格式文档,用于静态部署或离线阅读。其中第一个maven坐标是必须的。后两个maven坐标,当你在执行后面的代码过程中报下图中的错误,或者有的类无法导入的时候使用。

　　

　　

产生异常的原因已经有人在github上的问题给出解释了:当你使用swagger-core版本大于等于1.5.11,并且swagger-models版本小于1.5.11就会有异常发生,所以我们显式的引入这两个罐子,替换掉swagger2默认引入的这两个jar。

　　

　　

　　

下面的代码是通过编码方式实现的生成adoc格一起式文件的方式

　　 　　 　　@RunWith (SpringRunner.class) 　　@SpringBootTest (webEnvironment=SpringBootTest.WebEnvironment.DEFINED_PORT) 　　公开课DemoApplicationTests { 　　@Test 　　公共空间generateAsciiDocs()抛出异常{//输出Ascii格式 　　Swagger2MarkupConfig配置=new Swagger2MarkupConfigBuilder () 　　.withMarkupLanguage (MarkupLanguage.ASCIIDOC)//设置生成格式 　　.withOutputLanguage (Language.ZH)//设置语言中文还是其他语言 　　.withPathsGroupedBy (GroupBy.TAGS) 　　.withGeneratedExamples () 　　.withoutInlineSchema () 　　.build (); 　　 　　Swagger2MarkupConverter.from(新URL (http://localhost: 8888/v2/api文档)) 　　.withConfig(配置) 　　.build () 　　.toFile (Paths.get (“src/main/资源/docs/asciidoc ")); 　　} 　　} 　　 　　

使用RunWith注解和SpringBootTest注解,启动应用服务容器。SpringBootTest.WebEnvironment.DEFINED_PORT表示使用application.yml定义的端口,而不是随机使用一个端口进行测试,这很重要。

　　

Swagger2MarkupConfig是输出文件的配置,如文件的格式和文件中的自然语言等

　　

Swagger2MarkupConverter的从表示哪一个HTTP服务作为资源导出的源头(JSON格式),可以自己访问试一下这个链接.8888是我的服务端口,需要根据你自己的应用配置修改。

　　

去整理表示将导出文件存放的位置,不用加后缀名。也可以使用toFolder表示文件导出存放的路径。二者区别在于使用toFolder导出为文件目录下按标签标签分类的多个文件,使用去整理是导出一个文件(toFolder多个文件的合集)。

　　 　　 　　@Test 　　公共空间generateMarkdownDocsToFile()抛出异常{//输出减价到单文件 　　Swagger2MarkupConfig配置=new Swagger2MarkupConfigBuilder () 　　.withMarkupLanguage (MarkupLanguage.MARKDOWN) 　　.withOutputLanguage (Language.ZH) 　　.withPathsGroupedBy (GroupBy.TAGS) 　　.withGeneratedExamples () 　　.withoutInlineSchema () 　　.build (); 　　 　　Swagger2MarkupConverter.from(新URL (http://localhost: 8888/v2/api文档)) 　　.withConfig(配置) 　　.build () 　　.toFile (Paths.get (“src/main/资源/docs/减价”)); 　　}

将Swagger2文档导出为HTML或减价等格式离线阅读解析