目的与背景：
目的：对外暴露DBA Service必要的RESTful API，形成规整的API文档
背景：DBA Service后端采用Spring-boot，属于Spring家族，故生成API的工具采用基于Swagger2实现的SpringFox-Swagger2
一、API在线生成配置
1、通过Maven引入springfox-swagger2和 springfox-swagger-ui两个依赖，如下：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
|
|---|
2、创建Swagger2配置类
（1）在和WatchmanApplication启动类平行的路经下创建Swagger.java (类名自定)
（2）类内容如下：
@Configuration
@EnableSwagger2
public class Swagger2 {
@Value("${swagger.enable}")
private boolean isEnableSwagger;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(isEnableSwagger)
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("DBA Service 对外 API")
.description("DBA Service 对外提供的标准 RESTful API")
.termsOfServiceUrl("http://172.16.202.151:8888")
.contact("Yang Ren")
.version("1.0")
.build();
}
private Predicate<String> petstorePaths() {
return or(
regex("/api/inceptor.*")
);
}
}
|
|---|
其中，@Configuration@EnableSwagger2两个注解是装配和启用Swagger2的标志；
apiInfo()函数定义配置信息;createRestApi()返回API。
3、在Controller处配置要对外暴露的API注解
注解说明（具体百度，同时参考代码中的使用）：
控制类：@Api、@ApiOperation 、@ApiImplicitParams&@ApiImplicitParam 、@ApiResponses&@ApiResponse 、@ApiIgnore
4、WebUI形式访问
此时将项目正常启动，通过 http://localhost:8888/swagger-ui.html 来访问，localhost换成DBA Service所在的主机IP
二、生成离线html和pdf的静态API文档
需要借助Swagger2Markup开源工具生成AsciiDoc，AsciiDoc再被解析执行生成静态html和pdf。
5、Maven引入相关依赖，分两部分
（1）引入Swagger2Markup相关的依赖
|
...
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.1</version>
</dependency>
...
<repositories>
<repository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>jcenter-releases</id>
<name>jcenter</name>
<url>http://jcenter.bintray.com</url>
</repository>
</repositories>
|
|---|
（2）引入解析AsciiDoc来生成HTML和PDF的插件依赖
下面是结合各方自己调配的，生成HTML和PDF的通过<execution>标签使其独立各自执行一次，最终分别生成静态HTML和PDF文档。（其中一定要注意路经配置）
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<!-- Include Asciidoctor PDF for pdf generation -->
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.10.1</version>
</dependency>
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby-complete</artifactId>
<version>1.7.21</version>
</dependency>
</dependencies>
<!-- Configure generic document generation settings -->
<configuration>
<sourceDirectory>src/main/resources/docs/asciidoc/generated</sourceDirectory>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<toc>left</toc>
</attributes>
</configuration>
<!-- Since each execution can only handle one backend, run
separate executions for each desired output type -->
<executions>
<execution>
<id>output-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<outputDirectory>src/main/resources/docs/asciidoc/html</outputDirectory>
</configuration>
</execution>
<execution>
<id>output-pdf</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<outputDirectory>src/main/resources/docs/asciidoc/pdf</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
|
|---|
6、编写一个单元测试（我的单元测试类命名为Swagger2Test），目的是用来生成执行生成文档的代码，我的定义如下：
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class Swagger2Test {
@Test
public void generateAsciiDocs() throws Exception {
// 输出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8888/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("src/main/resources/docs/asciidoc/generated/all"));
}
}
|
|---|
本项目需求是生成一个完整的html和pdf，使用的是toFile()函数。其中必须要指定两项内容（绿色部分），前者是API的Json访问URL路经；后者是生成的执行生成文档的代码所保存到的路经。
备注：这里遇到一个坑，即Swagger2Markup依赖的common-beanutils和其他依赖这个包产生了冲突，我显示的把common-beanutils1.9.4放到了前边高优先级的位置，也就是之后不管哪个依赖的commons-beanutils都是1.9.4
7、运行单元测试（Swagger2Test）
注意：运行前一定要关闭IDE里启动的DBA Service，否则启动单元测试就拿不到Application Context，一定是冲突了。
正确执行完单元测试，可以看到/src/main/resources/docs/asciidoc/generated路经（这个路经就是单元测试中配置的那个路经）下多出了一个all.adoc文件。
这个all.adoc文件就是用来执行生成html和pdf的原始代码。我的all.adoc在IDEA中如下图：
8、执行如下两条maven命令即可生成HTML和PDF静态文档，我的生成后在IDEA中如下图：
-
mvn asciidoctor:process-asciidoc
- mvn generate-resources
|
|---|
