微服务: Swagger生成Markdown文档

发表于 | 分类于 |

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

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

1568529858131

简介

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

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

集成 swagger2markup

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

1
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，如图：

1568529858131

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<!--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 文件中添加如下内容，示例如下：

1
2
3
4
5
6
7
8
9
10
11
<!--不加这个，swagger2markup 找不到-->
<repositories>
    <repository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

编写测试代码

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
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 这个方法，右键该方法，出现弹框如下图：

1568529858131

直接选择 Run generateMarkdownFile 即可开始。

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

1
Failed to read the Swagger source

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

生成的文件如下：

1568529858131

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

同理，也可以使用下面的方法生成 adoc 格式（这种格式的文档需要使用其他工具生成 PDF 或者 HTML 文件）的文档，如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@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));
}

如果你在使用 generateDocsFile() 这个方法发生如下的错误：

1
java.lang.NoClassDefFoundError: nl/jworks/markdown_to_asciidoc/Converter

需要在你的 settings.xml 文件（一般在 C:\Users\username\.m2 目录下面，如果没有就新建一个吧）中增加阿里的镜像，如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">

    <mirrors>
        <mirror>
            <id>nexus-aliyun</id>
            <mirrorOf>*</mirrorOf>
            <name>Nexus aliyun</name>
            <url>https://maven.aliyun.com/repository/jcenter</url>
        </mirror>
    </mirrors>

</settings>

保存，然后去 IDEA 中重新运行测试方法即可。

如果你之前修改过 settings.xml 文件的位置，可以参考 idea设置maven配置文件setting.xml的位置 这篇文章去找到该文件再修改。

打烊，手工！

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