简介
swagger我们已经不陌生了，另外可以借助于swagger-ui，可以实现动态的、可测试的API文档。
本文主要介绍如何使用swagger2markup生成静态的HTML及PDF文档。
生成的文档样式如下：
swagger2markup主页
GitHub主页：
https://github.com/Swagger2Markup/swagger2markup
实现方式
swagger2markup的实现方式比较绕，pom.xml里的依赖也比较多，而且每次构建都生成文档的话，需要耗费较长的时间。
所以不建议直接集成到工程内部，可以将它独立成一个工程出来，专门用于生成文档。
配置及代码
配置及代码不多，就不上传github了，在下面直接贴出来。
实现方式大体是：
- 运行单元测试采集远程的swagger.json文件并保存到本地
- maven插件将swagger.json转换为asciidoc
- 将asciidoc再转为html+pdf。
用到了custom.baseurl这个JVM自定义的参数。默认情况下采集127.0.0.1:8080下的应用。
也可以在mvn后面指定-Dcustom.baseurl=xx.xx.xx.xx来实现自定义的采集，如果微服务较多，可以用start.sh脚本来进行批量采集
pom.xml
4.0.0
com.foo.bar
apidocs
1.0.0
jar
apidocs
ApiDocs
UTF-8
UTF-8
1.8
127.0.0.1:8080
1.3.1
${project.basedir}/src/docs/asciidoc
${project.build.directory}/swagger
${project.build.directory}/asciidoc/snippets
${project.build.directory}/asciidoc/generated
${project.build.directory}/asciidoc/html
${project.build.directory}/asciidoc/pdf
${swagger.output.dir}/swagger.json
org.springframework.boot
spring-boot-starter-parent
1.5.4.RELEASE
org.springframework.boot
spring-boot-starter-test
io.github.swagger2markup
swagger2markup-spring-restdocs-ext
${swagger2markup.version}
test
io.springfox
springfox-staticdocs
2.4.0
io.github.robwin
assertj-swagger
0.2.0
test
org.springframework.restdocs
spring-restdocs-mockmvc
src/main/resources
true
org.apache.maven.plugins
maven-compiler-plugin
3.3
${java.version}
${java.version}
${java.version}
UTF-8
false
org.apache.maven.plugins
maven-surefire-plugin
${swagger.output.dir}
${swagger.snippetOutput.dir}
${custom.baseurl}
io.github.swagger2markup
swagger2markup-maven-plugin
${swagger2markup.version}
io.github.swagger2markup
swagger2markup-import-files-ext
${swagger2markup.version}
io.github.swagger2markup
swagger2markup-spring-restdocs-ext
${swagger2markup.version}
${swagger.input}
${generated.asciidoc.directory}
ASCIIDOC
TAGS
${project.basedir}/src/docs/asciidoc/extensions/overview
${project.basedir}/src/docs/asciidoc/extensions/definitions
${project.basedir}/src/docs/asciidoc/extensions/paths
${project.basedir}src/docs/asciidoc/extensions/security/
${swagger.snippetOutput.dir}
true
test
convertSwagger2markup
org.asciidoctor
asciidoctor-maven-plugin
1.5.3
org.asciidoctor
asciidoctorj-pdf
1.5.0-alpha.10.1
org.jruby
jruby-complete
1.7.21
${asciidoctor.input.directory}
index.adoc
book
left
3
${generated.asciidoc.directory}
output-html
test
process-asciidoc
html5
${asciidoctor.html.output.directory}
output-pdf
test
process-asciidoc
pdf
${asciidoctor.pdf.output.directory}
org.apache.maven.plugins
maven-jar-plugin
2.4
true
lib/
io.github.robwin.swagger2markup.petstore.Application
maven-dependency-plugin
package
copy-dependencies
${project.build.directory}/lib
maven-resources-plugin
2.7
copy-resources
prepare-package
copy-resources
${project.build.outputDirectory}/static/docs
${asciidoctor.html.output.directory}
${asciidoctor.pdf.output.directory}
JUnit测试类
package com.sitech.sdtools;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.web.client.RestTemplate;
import java.io.BufferedWriter;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
@RunWith(SpringRunner.class)
@AutoConfigureRestDocs(outputDir = "build/asciidoc/snippets")
public class Swagger2MarkupTest {
private RestTemplate restTemplate = new RestTemplate();
@Test
public void createSpringfoxSwaggerJson() throws Exception {
String baseurl = System.getProperty("custom.baseurl");
String swaggerUrl = "http://" + baseurl + "/v2/api-docs";
String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
System.out.println("swaggerUrl: " + swaggerUrl);
System.out.println("outputDir: " + outputDir);
String swaggerJson = restTemplate.getForObject(swaggerUrl, String.class);
Files.createDirectories(Paths.get(outputDir));
try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)) {
writer.write(swaggerJson);
} catch (Exception e) {
e.printStackTrace();
}
}
}
批量shell脚本
start.sh
#!/usr/bin/env bash
# 自定义工程名及URL
prjnames=("project1" "project2" "project3")
prjurls=("xx.xx.xx.xx:7477" "xx.xx.xx.xx:23053" "xx.xx.xx.xx:24275")
# 默认参数
datestr=`date +%Y%m%d`
srcdir=./target/asciidoc/html
destdir=./src/docs/html/${datestr}
mkdir ${destdir}
# 循环生成文档
for prjname in ${prjnames[@]}
do
prjurl=${prjurls[${i}]}
echo "文档生成开始 - ${prjname} - ${prjurl}"
mvn clean test -Dcustom.baseurl=${prjurl}
cp ${srcdir}/index.html ${destdir}/${prjname}.html
i=$((i+1))
done
单文档生成步骤
- 先本机将需要生成API文档的工程启动，IP及端口指定为127.0.0.1:8080
- 在本工程下运行
mvn clean test - 在target/asciidoc/html中查看API文档并拷贝出来
批量文档生成步骤
- 在DCOS中将所有服务启动
- 修改start.sh中的prjurls
- 执行
./start.sh - 在
src/docs/html/日期/中查看生成的API文档