Spring Boot 2.x基础教程:Swagger静态文档的生成
前言
通过之前的两篇关于swagger入门以及具体使用细节的介绍之后,我们已经能够轻松地为spring mvc的web项目自动构建出api文档了。如果您还不熟悉这块,可以先阅读:
在这两篇文章中,我们构建的文档必须通过在项目中整合swagger-ui
、或使用单独部署的swagger-ui
和/v2/api-docs
返回的配置信息才能展现出您所构建的api文档。而有些时候,我们可能只需要提供静态文档给其他对接方的时候,我们要如何快速轻便的产生静态api文档呢?
接下来我们就来学习一个解决该问题的工具:swagger2markup。
swagger2markup简介
swagger2markup是github上的一个开源项目。该项目主要用来将swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用,比如:asciidoc、markdown、confluence。
项目主页:https://github.com/swagger2markup/swagger2markup
如何使用
在使用swagger2markup之前,我们先需要准备一个使用了swagger的web项目,可以是直接使用swagger2的项目,也可以使用spring boot 2.x基础教程:使用swagger2构建强大的api文档一文中构建的项目。读者可以通过下面的仓库获取:
- github:https://github.com/dyc87112/springboot-learning/tree/2.x
- gitee:https://gitee.com/didispace/springboot-learning/tree/2.x
接下来,我们将利用这个项目中的chapter2-2
模块作为基础来来生成几种不同格式的静态文档。
生成 asciidoc 文档
生成 asciidoc 文档的方式有两种:
通过java代码来生成
第一步:编辑pom.xml
增加需要使用的相关依赖和仓库
<dependencies> ... <dependency> <groupid>io.github.swagger2markup</groupid> <artifactid>swagger2markup</artifactid> <version>1.3.3</version> <scope>test</scope> </dependency> </dependencies> <repositories> <repository> <snapshots> <enabled>false</enabled> </snapshots> <id>jcenter-releases</id> <name>jcenter</name> <url>http://jcenter.bintray.com</url> </repository> </repositories>
本身这个工具主要就临时用一下,所以这里我们把scope
设置为test,这样这个依赖就不会打包到正常运行环境中去。
第二步:编写一个单元测试用例来生成执行生成文档的代码
@runwith(springrunner.class) @springboottest(webenvironment = springboottest.webenvironment.defined_port) public class demoapplicationtests { @test public void generateasciidocs() throws exception { url remoteswaggerfile = new url("http://localhost:8080/v2/api-docs"); path outputdirectory = paths.get("src/docs/asciidoc/generated"); // 输出ascii格式 swagger2markupconfig config = new swagger2markupconfigbuilder() .withmarkuplanguage(markuplanguage.asciidoc) .build(); swagger2markupconverter.from(remoteswaggerfile) .withconfig(config) .build() .tofolder(outputdirectory); } }
以上代码内容很简单,大致说明几个关键内容:
-
markuplanguage.asciidoc
:指定了要输出的最终格式。除了asciidoc
之外,还有markdown
和confluence_markup
,分别定义了其他格式,后面会具体举例。 -
from(remoteswaggerfile
:指定了生成静态部署文档的源头配置,可以是这样的url形式,也可以是符合swagger规范的string类型或者从文件中读取的流。如果是对当前使用的swagger项目,我们通过使用访问本地swagger接口的方式,如果是从外部获取的swagger文档配置文件,就可以通过字符串或读文件的方式 -
tofolder(outputdirectory)
:指定最终生成文件的具体目录位置
在执行了上面的测试用例之后,我们就能在当前项目的src目录下获得如下内容:
src --docs ----asciidoc ------generated --------definitions.adoc --------overview.adoc --------paths.adoc --------security.adoc
可以看到,这种方式在运行之后就生成出了4个不同的静态文件。
输出到单个文件
如果不想分割结果文件,也可以通过替换tofolder(paths.get("src/docs/asciidoc/generated")
为tofile(paths.get("src/docs/asciidoc/generated/all"))
,将转换结果输出到一个单一的文件中,这样可以最终生成html的也是单一的。
通过 maven 插件来生成
除了通过上面编写java代码来生成的方式之外,swagger2markup还提供了对应的maven插件来使用。对于上面的生成方式,完全可以通过在pom.xml
中增加如下插件来完成静态内容的生成。
<plugin> <groupid>io.github.swagger2markup</groupid> <artifactid>swagger2markup-maven-plugin</artifactid> <version>1.3.3</version> <configuration> <swaggerinput>http://localhost:8080/v2/api-docs</swaggerinput> <outputdir>src/docs/asciidoc/generated-by-plugin</outputdir> <config> <swagger2markup.markuplanguage>asciidoc</swagger2markup.markuplanguage> </config> </configuration> </plugin>
在使用插件生成前,需要先启动应用。然后执行插件,就可以在src/docs/asciidoc/generated-by-plugin
目录下看到也生成了上面一样的adoc文件了。
生成html
在完成了从swagger文档配置文件到asciidoc的源文件转换之后,就是如何将asciidoc转换成可部署的html内容了。这里继续在上面的工程基础上,引入一个maven插件来完成。
<plugin> <groupid>org.asciidoctor</groupid> <artifactid>asciidoctor-maven-plugin</artifactid> <version>1.5.6</version> <configuration> <sourcedirectory>src/docs/asciidoc/generated</sourcedirectory> <outputdirectory>src/docs/asciidoc/html</outputdirectory> <backend>html</backend> <sourcehighlighter>coderay</sourcehighlighter> <attributes> <toc>left</toc> </attributes> </configuration> </plugin>
通过上面的配置,执行该插件的asciidoctor:process-asciidoc
命令之后,就能在src/docs/asciidoc/html
目录下生成最终可用的静态部署html了。在完成生成之后,可以直接通过浏览器来看查看,你就能看到类似下图的静态部署结果:
是不是感觉似曾相识呢?是的,spring cloud的e版之前的文档也是这样的!!!
markdown 与 confluence 的支持
要生成markdown和confluence的方式非常简单,与上一篇中的方法类似,只需要修改一个参数即可。
生成 markdown 和 confluence 文档
生成方式有一下两种:
- 通过java代码来生成:只需要修改
withmarkuplanguage
属性来指定不同的格式以及tofolder
属性为结果指定不同的输出目录。
生成markdown的代码片段:
url remoteswaggerfile = new url("http://localhost:8080/v2/api-docs"); path outputdirectory = paths.get("src/docs/markdown/generated"); // 输出ascii格式 swagger2markupconfig config = new swagger2markupconfigbuilder() .withmarkuplanguage(markuplanguage.markdown) .build(); swagger2markupconverter.from(remoteswaggerfile) .withconfig(config) .build() .tofolder(outputdirectory);
生成confluence的代码片段:
url remoteswaggerfile = new url("http://localhost:8080/v2/api-docs"); path outputdirectory = paths.get("src/docs/confluence/generated"); // 输出ascii格式 swagger2markupconfig config = new swagger2markupconfigbuilder() .withmarkuplanguage(markuplanguage.confluence_markup) .build(); swagger2markupconverter.from(remoteswaggerfile) .withconfig(config) .build() .tofolder(outputdirectory);
在执行了上面的设置内容之后,我们就能在当前项目的src目录下获得如下内容:
src --docs ----confluence ------generated --------definitions.txt --------overview.txt --------paths.txt --------security.txt ----markdown ------generated --------definitions.md --------overview.md --------paths.md --------security.md
可以看到,运行之后分别在markdown和confluence目录下输出了不同格式的转换内容。如果读者想要通过插件来生成,直接参考上一节内容,只需要修改插件配置中的swagger2markup.markuplanguage
即可支持输出其他格式内容。
最后,我们一起来看看生成的markdown和confluence文档要怎么使用
markdown的部署
markdown目前在文档编写中使用非常常见,所以可用的静态部署工具也非常多,比如:hexo、jekyll等都可以轻松地实现静态化部署,也可以使用一些saas版本的文档工具,比如:语雀等。具体使用方法,这里按照这些工具的文档都非常详细,这里就不具体介绍了。
confluence的部署
相信很多团队都使用confluence作为文档管理系统,所以下面具体说说confluence格式生成结果的使用。
第一步:在confluence的新建页面的工具栏中选择{}markup
第二步:在弹出框的insert
选项中选择confluence wiki
,然后将生成的txt文件中的内容,黏贴在左侧的输入框中;此时,在右侧的阅览框可以看到如下图的效果了。
注意:所以insert
选项中也提供了markdown格式,我们也可以用上面生成的markdown结果来使用,但是效果并不好,所以在confluence中使用专门的生成结果为佳。
代码示例
本文的完整工程可以查看下面仓库中的chapter2-5
目录:
- github:https://github.com/dyc87112/springboot-learning/tree/2.x
- gitee:https://gitee.com/didispace/springboot-learning/tree/2.x
如果您觉得本文不错,欢迎star支持,您的关注是我坚持的动力!
参考资料
- [1] https://github.com/swagger2markup/swagger2markup
- [2] http://blog.didispace.com/swagger2markup-asciidoc/
- [3] http://blog.didispace.com/swagger2markup-markdown-confluence/
欢迎关注我的公众号:程序猿dd,获得独家整理的学习资源和日常干货推送。
如果您对我的专题内容感兴趣,也可以关注我的博客:
上一篇: 《三国志》和《三国演义》哪个好看?哪一本更值得读?
下一篇: C++贪心算法实现活动安排问题