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