前言

最近公司正好需要整理接口文檔，就想把Swagger2的文檔導(dǎo)出來(lái)。

開(kāi)始配置

pom.xml

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.3</version>
    <scope>test</scope>
</dependency>
<!-- https://mvnrepository.com/artifact/commons-beanutils/commons-beanutils -->
<dependency>
    <groupId>commons-beanutils</groupId>
    <artifactId>commons-beanutils</artifactId>
    <version>1.9.2</version>
    <scope>test</scope>
</dependency>

使用單元測(cè)試生成文檔

package com.asiainfo.aigov;

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.GroupBy;
import io.github.swagger2markup.Language;
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(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class Swagger2Test {

    @Test
    public void generateAsciiDocs() throws Exception {
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withoutInlineSchema()
                .build();
        Swagger2MarkupConverter.from(new URL("http://localhost:8080/familydoctor-webapp/v2/api-docs"))
                .withConfig(config)
                .build()
//                .toFolder(Paths.get("./docs"));
                .toFile(Paths.get("./docs/api"));
    }
    
}

結(jié)后語(yǔ)

生成的文檔是md格式，可以放到有道云筆記里，再導(dǎo)出為pdf或html，也可以用pandoc轉(zhuǎn)成word。