swagger2markdown使用文

swagger2markdown是一种将swagger生成的接口文档转化为markdown格式文档的工具，使用很简便，下面是详细说明。

一、使用环境的构建

构建一个使用了swagger的spring-boot-web工程

修改pom.xml，加入swagger2markdown依赖

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.1</version>
</dependency>

创建一个junit测试类，也可以用构建项目时，默认生成的测试类

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

import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;

@RunWith(SpringRunner.class)
@SpringBootTest
public class Swagger2markdown1ApplicationTests {

    @Test
    public void genrateMarkdown() throws Exception {

        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder().withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .build();

        Swagger2MarkupConverter
                .from(new URL("http://localhost:8080/javashop/v2/api-docs?group=%E5%85%A8%E9%83%A8%E5%88%86%E7%BB%84"))
                .withConfig(config).build().toFolder(Paths.get("src/test"));
    }

}

代码中url里%E5%85%A8%E9%83%A8%E5%88%86%E7%BB%84的意思“全部分组”，这个路径只有使用swagger的项目启动时，才会生效，所以在转化文档时，需要启动要导出文档的项目。

src/test是指生成的markdown文档保存在src下的test文件夹里。

具体使用

运行Junit测试，即可获得相应的文档：

definitions文件包含所有被swagger标注的实体类

overview文件包含所有被swagger标注的controller

paths文件包含所有被swagger标注的url路径

security目前是空的