Swagger接口如何生成Html离线文档 - 技术，沉淀 - OSCHINA - 中文开源技术交流社区

安宇雨 - 随手采集
2024-01-03 16:12:20
随手采集
0000-未整理-等待研究

转：

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/iflyendless/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离线文档

看起来是不是有模有样的！建议正在使用 swagger 的朋友可以感受一下生成的离线 Html。

实现

完整源码见：https://github.com/iflyendless/Swagger2Html

引入依赖：


  
  
    
   
   
    
    io.github.swagger2markup
   
   
    
   
   
    
    swagger2markup
   
   
    
   
   
    
    1.3.3
   
   

  
  


  
  
    
   
   
    
    org.asciidoctor
   
   
    
   
   
    
    asciidoctorj
   
   
    
   
   
    
    2.4.3

代码实现：

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);
        }
    }
}

随手记录，方便你我他！

转：