使用Swagger2Markup归档swagger生成的API文档
文章出处: http://blog.didispace.com/swagger2markup-asciidoc/
说明
项目中使用Swagger之后,我们能够很轻松的管理API文档,并非常简单的模拟接口调用,但是构建的文档必须通过在项目中整合 swagger-ui
、或使用单独部署的 swagger-ui
和 /v2/api-docs
返回的配置信息才能展现出您所构建的API文档。本文将在使用Swagger的基础上,再介绍一种生成静态API文档的方法,以便于构建更轻量部署和使用的API文档。
Swagger2Markup简介
Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用,比如:AsciiDoc、Markdown、Confluence。
项目主页:https://github.com/Swagger2Markup/swagger2markup
如何使用
在使用Swagger2Markup之前,我们先需要准备一个使用了Swagger的Web项目,可以是直接使用Swagger2的项目
引入依赖
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.1</version>
</dependency> <repositories>
<repository>
<snapshots>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
</snapshots>
<id>jcenter-releases</id>
<name>jcenter</name>
<url>http://jcenter.bintray.com</url>
</repository>
</repositories>
编写一个单元测试用例来生成执行生成文档的代码
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class SwaggerDemoApplicationTests {<span class="hljs-comment">/**
* 生成AsciiDocs格式文档
* </span><a href="https://github.com/throws" title="@throws" class="at-link"><span class="hljs-comment"><span class="hljs-doctag">@throws</span></span></a><span class="hljs-comment"> Exception
*/</span>
<a href="https://github.com/Test" title="@Test" class="at-link"><span class="hljs-meta">@Test</span></a>
<span class="hljs-function"><span class="hljs-keyword">public</span> <span class="hljs-keyword">void</span> <span class="hljs-title">generateAsciiDocs</span><span class="hljs-params">()</span> <span class="hljs-keyword">throws</span> Exception </span>{
<span class="hljs-comment">// 输出Ascii格式</span>
Swagger2MarkupConfig config = <span class="hljs-keyword">new</span> Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build(); Swagger2MarkupConverter.from(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">"http://localhost:8080/v2/api-docs"</span>))
.withConfig(config)
.build()
.toFolder(Paths.get(<span class="hljs-string">"./docs/asciidoc/generated"</span>));
} <span class="hljs-comment">/**
* 生成Markdown格式文档
* </span><a href="https://github.com/throws" title="@throws" class="at-link"><span class="hljs-comment"><span class="hljs-doctag">@throws</span></span></a><span class="hljs-comment"> Exception
*/</span>
<a href="https://github.com/Test" title="@Test" class="at-link"><span class="hljs-meta">@Test</span></a>
<span class="hljs-function"><span class="hljs-keyword">public</span> <span class="hljs-keyword">void</span> <span class="hljs-title">generateMarkdownDocs</span><span class="hljs-params">()</span> <span class="hljs-keyword">throws</span> Exception </span>{
<span class="hljs-comment">// 输出Markdown格式</span>
Swagger2MarkupConfig config = <span class="hljs-keyword">new</span> Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build(); Swagger2MarkupConverter.from(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">"http://localhost:8080/v2/api-docs"</span>))
.withConfig(config)
.build()
.toFolder(Paths.get(<span class="hljs-string">"./docs/markdown/generated"</span>));
}
/**
* 生成Confluence格式文档
* @throws Exception
*/
@Test
public void generateConfluenceDocs() throws Exception {
// 输出Confluence使用的格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("./docs/confluence/generated"));
}
/**
* 生成AsciiDocs格式文档,并汇总成一个文件
* @throws Exception
*/
@Test
public void generateAsciiDocsToFile() throws Exception {
// 输出Ascii到单文件
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("./docs/asciidoc/generated/all"));
}
/**
* 生成Markdown格式文档,并汇总成一个文件
* @throws Exception
*/
@Test
public void generateMarkdownDocsToFile() throws Exception {
// 输出Markdown到单文件
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("./docs/markdown/generated/all"));
}
使用maven插件生成HTML文档
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>./docs/asciidoc/generated</sourceDirectory>
<outputDirectory>./docs/asciidoc/html</outputDirectory>
<headerFooter>true</headerFooter>
<doctype>book</doctype>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<!--菜单栏在左边-->
<toc>left</toc>
<!--多标题排列-->
<toclevels>3</toclevels>
<!--自动打数字序号-->
<sectnums>true</sectnums>
</attributes>
</configuration>
</plugin>
</plugins>
效果
实际项目应用后效果
- [实际项目应用后效果](http://cdn-blog.jetbrains.org.cn/doc/all.html)
代码
https://github.com/changdaye/swagger-demo
鸣谢
文章出处: http://blog.didispace.com/swagger2markup-asciidoc/
使用Swagger2Markup归档swagger生成的API文档的更多相关文章
- Spring Boot 集成 Swagger 生成 RESTful API 文档
原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档 简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...
- springmvc使用swagger生成rest api文档
pom.xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-s ...
- Swagger UI及 Swagger editor教程 API文档搭配 Node使用
swagger ui 是一个在线文档生成和测试的利器,目前发现最好用的.为啥好用呢?打开 demo,支持API自动生成同步的在线文档些文档可用于项目内部API审核方便测试人员了解 API这些文档可作为 ...
- Spring Boot学习笔记 - 整合Swagger2自动生成RESTful API文档
1.添加Swagger2依赖 在pom.xml中加入Swagger2的依赖 <!--swagger2--> <dependency> <groupId>io.spr ...
- Swagger UI教程 API 文档神器 搭配Node使用
ASP.NET Web API 使用Swagger生成在线帮助测试文档 Swagger 生成 ASP.NET Web API 前言 swagger ui是一个API在线文档生成和测试的利器,目前发现最 ...
- Golang使用swaggo自动生成Restful API文档
#关于Swaggo 相信很多程序猿和我一样不喜欢写API文档.写代码多舒服,写文档不仅要花费大量的时间,有时候还不能做到面面具全.但API文档是必不可少的,相信其重要性就不用我说了,一份含糊的文档甚至 ...
- GhostDoc:生成.NET API文档的工具 (帮忙文档)
在 Sandcastle:生成.NET API文档的工具 (帮忙文档) 后提供另一个生成API文档的工具. 1) 准备工作 安装GhostDoc Proc. 收费的哦.... 这个工具的优势是不像 ...
- 使用jsdoc-toolkit来自动生成js api文档
近来前端组小盆友开发的类库越来越多,很多情况下彼此不知道写了些什么方法,为了更好的合作提高工作效率,找了个比较好的api文档生成方法.使用jsdoc-toolkit来自动生成js api文档. 一. ...
- Grunt-jsdoc生成JS API文档
Grunt-jsdoc生成JS API文档 具体的请看官网 https://github.com/krampstudio/grunt-jsdoc 一:首先确保本机电脑上是否已经安装了nodejs和np ...
随机推荐
- JPA单向和双向关系
单向关系 @JoinColumn 双向关系 @OneToMany @ManyToMany mappedBy
- 【题解】Ride to Office
题目描述 起点与终点相隔4500米.现Charley 需要从起点骑车到终点.但是,他有个习惯,沿途需要有人陪伴,即以相同的速度, 与另外一个人一起骑.而当他遇到以更快的速度骑车的人时,他会以相应的速度 ...
- python获取港股通每日成交信息
接口:ggt_daily 描述:获取港股通每日成交信息,数据从2014年开始 限量:单次最大1000,总量数据不限制 积分:用户积2000积分可调取,5000积分无限制,请自行提高积分,具体请参阅本文 ...
- Linux下svn更新含有中文名称的库无法更新问题
Linux下更新含有中文名称的库文件时,出现如下提示: SVN Error: Can't convert string from native encoding to 'UTF-8' 通过google ...
- 【记录】centOS 搭建logstash +docker搭建elasticsearch伪集群+kibana链接集群elasticsearch节点
[注意]本文主要用于自我记录,注释较少. 安装logstash 1.上传logstash-6.4.3.tar.gz到服务中 2.tar –zxvf logstash-6.4.3.tar.gz 3.cd ...
- mysql几个常见错误记录
select时找不到表:大小写问题 show variables like '%lower_case_table_names%'; MySQL表名大小写敏感导致的问题 使用help_topic时的se ...
- 【Luogu】【关卡2-6】贪心(2017年10月)
任务说明:贪心就是只考虑眼前的利益.对于我们人生来说太贪是不好的,不过oi中,有时是对的. P1090 合并果子 有N堆果子,只能两两合并,每合并一次消耗的体力是两堆果子的权重和,问最小消耗多少体力. ...
- 【转载】网易极客战记官方攻略-地牢-严酷考验 B
关卡连接:https://codecombat.163.com/play/level/the-gauntlet-b 免费试玩:https://codecombat.163.com/play 使用你的所 ...
- centos7 nodejs二进制安装
1.安装文件下载 1.下载地址:http://nodejs.cn/download/ 2.选择一个合适的版本下载 2.安装步骤 1.将安装包上传到指定位置(我习惯放到:/usr/local/appli ...
- 关于nodejs+koa中的跨域问题与koa项目创建
项目快速创建 -1. 安装koa-generator npm install -g koa-generator -2. 使用koa-generator生成koa2项目, koa2 test -3. 完 ...