Swagger接口如何生成Html离线文档

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

小记Swagger接口生成Html离线文档

由来

很多人用

swagger2markup

asciidoctor-maven-plugin

由于

swagger2markup

所以, 干脆把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, ad
56c
ocPath);

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", "
56c
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);
}
}
}

随手记录，方便你我他！