场景

有时候需要为前端开发者提供Restful Api说明文档，通过word文档创建和修改非常耗时，希望有一种比较便捷的第三方库可以减少生成Api说明文档的工作量

基于Spring的Restful Api生成工具

术语解析

Springfox-swagger2
Swagger是一个可以生成基于多种语言编写的Restful Api的文档生成工具，详见这里。
查看Springfox-swagger2注解文档，请点击这里
Swagger2markup
Swagger2markup是一个使用java编写的将Swagger语义转换成markdown、asciidoc文本格式的开源项目
Swagger2Markerup的详细说明请见这里
Asciidoc
AsciiDoc是一种MarkDown的扩展文本格式，AsciiDoc相比MarkDown更适合编写类似API文档，学术文档这样的文档。
详见这里
Asciidoctor
asciidoctor是一个由ruby编写的可以将 asciidoc转换成html、pdf的开源项目，这个项目有java版本和maven插件，详见这里

接口生成原理

generate an up-to-date Swagger JSON file during an unit or integration test
使用Springfox-swagger2生成swagger json文件
convert the Swagger JSON file into AsciiDoc
使用Swagger2markup将swagger json文件转换成asciidoc文档片段
add hand-written AsciiDoc documentation
编写asciidoc的文档(主要是组装步骤2中生成的asciidoc文档片段)
convert AsciiDoc into HTML and PDF
使用Asciidoctor将asciidoc转换成HTML 或pdf

Swagger部署说明

在pom引入下面依赖：

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
            <scope>test</scope>
        </dependency>

配置一个SwaggerConfig

@EnableSwagger2
@Configuration
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {

    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .securitySchemes(asList(
                        new OAuth(
                            "petstore_auth",
                            asList(new AuthorizationScope("write_pets", "modify pets in your account"),
                                    new AuthorizationScope("read_pets", "read your pets")),
                                Arrays.<GrantType>asList(new ImplicitGrant(new LoginEndpoint("http://petstore.swagger.io/api/oauth/dialog"), "tokenName"))
                        ),
                        new ApiKey("api_key", "api_key", "header")
                ))
                .select()
                .paths(Predicates.and(ant("/**"), Predicates.not(ant("/error")), Predicates.not(ant("/management/**")), Predicates.not(ant("/management*"))))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger Petstore")
                .description("Petstore API Description")
                .contact(new Contact("TestName", "http:/test-url.com", "test@test.de"))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .version("1.0.0")
                .build();
    }
}

运行Spring项目
运行项目后会发布Spring的路由器多了若干个对外的接口，其中一个是/v2/api-docs/。
通过这个接口可以获取到由Swagger生成的所有API接口的元数据。
Api界面部署
呈现由Swagger生成的API大概有两种方法（目前只找到两种）

Swagger自带有Swagger-UI可以直观显示API接口说明并可以在线调试
使用Swagger2Markerup插件和AsciiDoc插件可以将Swagger生成的JSON元数据转换成HTML、PDF

注意：springfox-swagger2是依赖与Spring MVC框架的！！

Swagger-UI部署

引入Swagger-UI依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>

运行Spring项目，并访问htttp://[host]:[ip]/swagger-ui.html

截图.png

其它的插入位置同理

swagger2markup-spring-restdocs-ext

插件说明

此插件可以自动将Spring rest doc生成的adoc片段添加到Paths说明部分的最后。
Spring Rest doc生成的adoc版片段：

curl-request.adoc
http-request.adoc
http-response.adoc
httpie-request.adoc

插件默认扫描前3个adoc，当然也可以通过withExplicitSnippets自定义扫描的文件名。

插件使用

maven插件部署
这里我们使用与上一个述件不同的部署方式，直接到通过代码配置插件

        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
            <version>1.0.0</version>
            <scope>compile</scope>
        </dependency>

配置

        Map<String, String> configMap = new HashMap<>(); 
        configMap.put("swagger2markup.extensions.springRestDocs.snippetBaseUri", "docs/restful/snippets");
        configMap.put("swagger2markup.extensions.springRestDocs.defaultSnippets", "true");
        configMap.put(Swagger2MarkupProperties.PATHS_GROUPED_BY, GroupBy.TAGS.name());
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder(configMap)

其中snippetBaseUri是Spring Rest Doc生成文档的位置；defaultSnippets指明是否使用默认的文件名扫描，如果设置为false，需要手工创建插件并通过withExplicitSnippets自行设置扫描的文件名。