文章出处: 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的项目

  1. 引入依赖

     <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>

  1. 编写一个单元测试用例来生成执行生成文档的代码

     @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"));
}
  1. 使用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>

效果

实际项目应用后效果

代码

https://github.com/changdaye/swagger-demo

鸣谢

文章出处: http://blog.didispace.com/swagger2markup-asciidoc/

使用Swagger2Markup归档swagger生成的API文档的更多相关文章

  1. Spring Boot 集成 Swagger 生成 RESTful API 文档

    原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档 简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...

  2. springmvc使用swagger生成rest api文档

    pom.xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-s ...

  3. Swagger UI及 Swagger editor教程 API文档搭配 Node使用

    swagger ui 是一个在线文档生成和测试的利器,目前发现最好用的.为啥好用呢?打开 demo,支持API自动生成同步的在线文档些文档可用于项目内部API审核方便测试人员了解 API这些文档可作为 ...

  4. Spring Boot学习笔记 - 整合Swagger2自动生成RESTful API文档

    1.添加Swagger2依赖 在pom.xml中加入Swagger2的依赖 <!--swagger2--> <dependency> <groupId>io.spr ...

  5. Swagger UI教程 API 文档神器 搭配Node使用

    ASP.NET Web API 使用Swagger生成在线帮助测试文档 Swagger 生成 ASP.NET Web API 前言 swagger ui是一个API在线文档生成和测试的利器,目前发现最 ...

  6. Golang使用swaggo自动生成Restful API文档

    #关于Swaggo 相信很多程序猿和我一样不喜欢写API文档.写代码多舒服,写文档不仅要花费大量的时间,有时候还不能做到面面具全.但API文档是必不可少的,相信其重要性就不用我说了,一份含糊的文档甚至 ...

  7. GhostDoc:生成.NET API文档的工具 (帮忙文档)

    在 Sandcastle:生成.NET API文档的工具 (帮忙文档) 后提供另一个生成API文档的工具.   1) 准备工作 安装GhostDoc Proc. 收费的哦.... 这个工具的优势是不像 ...

  8. 使用jsdoc-toolkit来自动生成js api文档

    近来前端组小盆友开发的类库越来越多,很多情况下彼此不知道写了些什么方法,为了更好的合作提高工作效率,找了个比较好的api文档生成方法.使用jsdoc-toolkit来自动生成js api文档. 一.  ...

  9. Grunt-jsdoc生成JS API文档

    Grunt-jsdoc生成JS API文档 具体的请看官网 https://github.com/krampstudio/grunt-jsdoc 一:首先确保本机电脑上是否已经安装了nodejs和np ...

随机推荐

  1. java 并发——AbstractQueuedSynchronizer

    java 并发--AbstractQueuedSynchronizer 简介 abstract class AbstractQueuedSynchronizer extends AbstractOwn ...

  2. 06、python的基础-->编码小知识

    1.编码类型ascii A : 00000010 8位 一个字节 unicode A : 00000000 00000001 00000010 00000100 32位 四个字节 中:00000000 ...

  3. jQuery选择器中空格的问题再探究

    jQuery选择器的空格问题,看似很小,但是差之毫厘谬以千里,让人很是恼火,<锋利的jQuery>书中有个经典的例子,我这里也拷贝下来,再加点自己的想法 <html> < ...

  4. 数据结构与算法简记--redis有序集合实现-跳跃表

    跳表 定义 为一个值有序的链表建立多级索引,比如每2个节点提取一个节点到上一级,我们把抽出来的那一级叫做索引或索引层.如下图所示,其中down表示down指针,指向下一级节点.以此类推,对于节点数为n ...

  5. 13-python基础—python3中的map()

    map() 会根据提供的函数对指定序列做映射. 第一个参数 function 以参数序列中的每一个元素调用 function 函数,返回包含每次 function 函数返回值的新列表. 通俗解释: m ...

  6. Light项目---vue搭建前端时遇见的一些问题

    css样式中设置的: opacity 表示透明度 将js对象存储到localStorge中 的时候,直接存储是不行的,会变成[object Object],都是这样的数据, 需要将其进行JSON化处理 ...

  7. KiCAD泪滴

    KiCAD泪滴 KiCAD没有自带的补泪滴功能,必须先下载一个插件,然后才能进行泪滴操作 链接 提取码:ey8o 1.下载泪滴插件,解压后将整个文件夹复制到目录  C:\Program Files\K ...

  8. iptables 防火墙(上)

    iptables 防火墙(上) 1. 防火墙概述 1.1 概念与作用 网络中的防火墙是一种将内部网络和外部网络分开的方法,是一种隔离技术.防火墙在内网与外网通信时进行访问控制,依据所设置的规则对数据包 ...

  9. 前端学习(十)初识js(笔记)

    js事件(公有属性) onclick=""  当点击...时! onmouseover="" 当鼠标移入...时!onmouseout="" ...

  10. js取整 - 优雅版(装逼必备)

    var a = 2.98; var z1 = ~~a; var z2 = a | 0; var z3 = a>>0; console.log(z1, z2, z3);     // 2, ...