Swagger接口如何生成Html離線文檔

A very simple tool that converts Swagger Api Document to Html File.

小記Swagger接口生成Html離線文檔

由來

很多人用swagger2markup以及asciidoctor-maven-plugin插件來生成html格式的文檔。

由於swagger2markup依賴的asm庫版本較低, 且依賴較多, 容易與項目中依賴的核心庫沖突。

所以, 干脆把Swagger接口文檔轉為Html文檔獨立出來, 做成一個小工具, 這樣就清爽干凈多了！

使用

# 下載源碼
git clone https://github.com/bytesfly/Swagger2Html.git

# 編譯打包
mvn clean package

# 使用target目錄下的jar包, 參數是swagger接口數據
java -jar Swagger2Html-1.0-SNAPSHOT-jar-with-dependencies.jar http://localhost:8080/v2/api-docs

當前目錄下便會新增api.html文件，用瀏覽器打開效果如下圖：

看起來是不是有模有樣的! 建議正在使用swagger的朋友可以感受一下生成的離線Html。

實現

完整源碼見：https://github.com/bytesfly/Swagger2Html

引入依賴：

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

<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj</artifactId>
    <version>2.4.3</version>
</dependency>

代碼實現：

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;
import org.asciidoctor.Asciidoctor;
import org.asciidoctor.AttributesBuilder;
import org.asciidoctor.OptionsBuilder;
import org.asciidoctor.SafeMode;

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

/**
 * Swagger接口文檔轉為html文檔
 */
public class Swagger2Html {

    private static final String DEFAULT_SWAGGER_API = "http://localhost:8080/v2/api-docs";

    private static final String DEFAULT_ADOC_PATH = "./api.adoc";

    private static final String DEFAULT_HTML_PATH = "./api.html";

    public static void main(String[] args) throws Exception {
        String swaggerApi = args.length > 0 ? args[0] : DEFAULT_SWAGGER_API;
        String adocPath = args.length > 1 ? args[1] : DEFAULT_ADOC_PATH;
        String htmlPath = args.length > 2 ? args[2] : DEFAULT_HTML_PATH;

        System.out.println("swaggerApi: " + swaggerApi);
        System.out.println("adocPath: " + adocPath);
        System.out.println("htmlPath: " + htmlPath);

        generateAsciiDocsToFile(swaggerApi, adocPath);

        convert2Html(adocPath, htmlPath);

        System.out.println("*** success!!! ***");
    }

    /**
     * 生成AsciiDocs格式文檔,並匯總成一個文件
     */
    private static void generateAsciiDocsToFile(String swaggerApi, String filePath) throws Exception {
        // 輸出Ascii到單個文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL(swaggerApi))
                .withConfig(config)
                .build()
                .toFileWithoutExtension(Paths.get(filePath));
    }

    /**
     * convert AsciiDoc files using AsciidoctorJ.
     * 參考: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/master/src/main/java/org/asciidoctor/maven/AsciidoctorMojo.java
     */
    private static void convert2Html(String sourceFile, String targetFile) throws Exception {
        try (Asciidoctor asciidoctor = Asciidoctor.Factory.create()) {
            AttributesBuilder attributes = AttributesBuilder.attributes()
                    .sourceHighlighter("coderay")
                    .attribute("toc", "left")
                    .attribute("toclevels", "3")
                    .attribute("sectnums");

            OptionsBuilder options = OptionsBuilder.options()
                    .docType("book")
                    .backend("html")
                    .safe(SafeMode.UNSAFE)
                    .headerFooter(true)
                    .attributes(attributes)
                    .toFile(new File(targetFile));

            asciidoctor.convertFile(new File(sourceFile), options);
        }
    }
}

隨手記錄，方便你我他！