Swagger2在DBA Service中生成RESTful API的实践

提示：扫一扫查出行
【扫一扫了解最新限行尾号】
复制提示

目的与背景：

目的：对外暴露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注解

注解说明（具体百度，同时参考代码中的使用）：

实体类：@ApiModel和@ApiModelProperty用于在通过对象接收参数时在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>

<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>

<configuration>
<sourceDirectory>src/main/resources/docs/asciidoc/generated</sourceDirectory>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<toc>left</toc>
</attributes>
</configuration>

<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中如下图：