转载

微服务: Swagger生成Markdown文档

国庆放假期间，看了一部 2018年上映的电影《本杰明.巴顿奇事》，豆瓣评分 8.9。影片讲述了一出生便拥有80岁老人形象的本杰明·巴顿，随着岁月的推移逐渐变得年轻，最终回到婴儿形态，并在苍老的恋人黛茜怀中离世的奇异故事。如果没有看过的小伙伴，推荐大家去看看，里面有很多关于人生的哲理。

本次文章封面图来自该电影。

简介

文章微服务: Swagger让你可以多抽一支烟给大家分享了如何在自己的 SpringBoot 工程中集成 Swagger 以及如何使用 Swagger 生成在线文档。今天跟大家分享以下如何使用 Swagger 生成离线的 Markdown 格式的文档，在阅读下面内容之前，还是希望大家能看一下微服务: Swagger让你可以多抽一支烟这篇文章。

本人是一个热爱 Markdown 的狂热分子，无论是写日记还是工作笔记我都会使用 Markdown工具来做，那种所见即所得的感觉有点暗爽。自己在网上也找了很多关于如何使用 Swagger 生成 Markdown 格式的文档，大多数文章都比较陈旧，好不容易找到一篇自认为还可以的文章去实践发现还是存在一些问题，于是经过摸索诞生了此文。

集成 swagger2markup

插件 Swagger2Markup 可以帮助我们将 Swagger 文档转换为离线的 Markdown 格式的文档， Swagger2Markup 介绍如下：

Swagger2Markup converts a Swagger JSON or YAML file into several AsciiDoc or GitHub Flavored Markdown documents which can be combined with hand-written documentation.

可以在 mvnrepository 仓库中搜索 swagger2markup ，如图：

微服务: Swagger生成Markdown文档

我使用的是第一个，当前版本是 1.3.3 ，在工程的 pom 文件中，需要集成 swagger 和 swagger2markup ，示例如下：

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!--swagger2markup-->
<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.3</version>
    <scope>test</scope>
</dependency>

如果你认为这样就可以了，那你接下来无法完成编译工作，因为根本下载不了 swagger2markup ，还需要在 pom 文件中添加如下内容，示例如下：

<!--不加这个，swagger2markup 找不到-->
<repositories>
    <repository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

编写测试代码

插件集成成功之后，接下来我们就可以去实现生成 Markdown 文档的梦想了，有点小鸡冻…

单元测试代码示例，如下：

import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.mock.web.MockHttpServletResponse;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.MvcResult;
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders;

import java.net.URL;
import java.nio.file.Paths;

@RunWith(SpringRunner.class)
@AutoConfigureMockMvc
@SpringBootTest
public class SpringbootApplicationTests{

    @Test
    public void generateMarkdownFile()throws Exception {
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.MARKDOWN)
        .build();

        URL apiUrl = new URL("http://localhost:8080/v2/api-docs");
        // 指定文件名称
        String markdownFileName = "src/docs/markdown/generated/MSBlog_Server_API";
        Swagger2MarkupConverter.from(apiUrl)
        .withConfig(config)
        .build()
        //指定生成目录下生成指定文件
        .toFile(Paths.get(markdownFileName));
    }
}

编写完成后，可以运行 generateMarkdownFile 这个方法，右键该方法，出现弹框如下图：

微服务: Swagger生成Markdown文档

直接选择 Run generateMarkdownFile 即可开始。

不出意外的话，会失败并且报如下错误：

Failed to read the Swagger source

因为我们是要从 http://localhost:8080/v2/api-docs 读取内容，所以首先需要将主工程运行起来即运行项目。运行成功之后，再来执行测试代码就可以成功了。

生成的文件如下：

微服务: Swagger生成Markdown文档

此时的我情不自禁的哼起了：“只要人人都献出一点爱，世界将变成美丽的人间” 的歌词，卧槽+n…总算可以了。

同理，也可以使用下面的方法生成 doc 格式的文档，如下：

@Test
public void generateDocsFile()throws Exception {
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .build();

    // 该地址不要写错
    URL apiUrl = new URL("http://localhost:8080/v2/api-docs");
    // 指定目录
    String dirName = "src/docs/markdown/generated";
    Swagger2MarkupConverter.from(apiUrl)
        .withConfig(config)
        .build()
        //指定生成目录
        .toFolder(Paths.get(dirName));
}

打烊手工！

一件事无论太晚或者太早，都不会阻拦你成为你想成为的那个人，这个过程没有时间的期限，只要你想，随时都可以开始~

微服务: Swagger生成Markdown文档