摘要：導讀在團隊協(xié)作的時候許多時候需要用到接口文檔，我們通常通過手工編寫大量重復格式的文檔，讓我想起了程序員最討厭的兩件事沒有文檔，編寫文檔。對應(yīng)的資料可自行谷歌。關(guān)于和官網(wǎng)是這樣描述的。我們可以理解為為基于構(gòu)建的自動生成文檔。

在團隊協(xié)作的時候許多時候需要用到接口文檔，我們通常通過手工編寫大量重復格式的文檔，讓我想起了程序員最討厭的兩件事：沒有文檔，編寫文檔。哈哈，如果使用過swagger的朋友應(yīng)該都很了解它帶給我們的便利，如果你還沒有使用swagger的話，正好打算編寫RESTful API文檔，這里有一篇文章Spring Boot中使用Swagger2構(gòu)建強大的RESTful API文檔可以幫助你在較短的時間內(nèi)構(gòu)建出一個線上文檔，有些時候我們需要生成離線文檔有該怎么做呢？帶著這個問題我們一起去出發(fā)。

Swagger - 前后端分離后的契約

通過Swagger進行API設(shè)計，與Tony Tam的一次對話

一個簡短的總結(jié)，更好的生成RESTful API文檔，提供相應(yīng)的測試功能，效果圖如下：

swagger為我們提供了生成在線文檔的功能，然而有些時候客戶需要的是離線文檔的api,有沒有什么較好的辦法可以通過swagger幫助我們生成離線文檔呢？

這就是今天的主角：Springfox和Spring Rest Docs幫我們做的事情
1.預備知識：
建議了解swagger、Asciidoc、asciidoctor-maven-plugin和SpringBoot Testing。對應(yīng)的資料可自行谷歌。
2.關(guān)于Springfox和Spring Rest Docs：
官網(wǎng)是這樣描述的Springfox：Automated JSON API documentation for API"s built with Spring。我們可以理解為為 基于Spring構(gòu)建的API自動生成文檔。

其實我們的思路就是把swagger在線文檔轉(zhuǎn)成staticdocs形式的文檔，引入相關(guān)的一些依賴 Spring Rest Docs的依賴spring-restdocs-mockmvc，離線文檔的依賴springfox-staticdocs，因為要在單元測試的時候生成文檔，所以再加測試相關(guān)的spring-boot-starter-test。

    org.springframework.boot
    spring-boot-starter-data-jpa



    com.h2database
    h2
    runtime


    org.springframework.boot
    spring-boot-starter-web


    org.springframework.boot
    spring-boot-starter-test


    io.springfox
    springfox-swagger2
    2.6.1


    io.springfox
    springfox-swagger-ui
    2.6.1


    org.springframework.restdocs
    spring-restdocs-mockmvc
    1.1.2.RELEASE
    test


    io.springfox
    springfox-staticdocs
    2.6.1


    com.alibaba
    fastjson
    1.2.8

我們使用asciidoctor-maven-plugin插件將Asciidoc格式轉(zhuǎn)成HTML5格式
了解更多： 使用介紹

 
    org.asciidoctor
    asciidoctor-maven-plugin
    
        
        
        ${asciidoctor.html.output.directory}
        index.adoc
        
            book
            left
            3
            ${generated.asciidoc.directory}
        
    
    
        
            output-html
            test
            
                process-asciidoc
            
            
                html
                
                    ${project.build.directory}/generated-snippets
                
            
        
    

import cn.sunxyz.domain.UserInfo;
import com.alibaba.fastjson.JSON;
import io.github.robwin.markup.builder.MarkupLanguage;
import io.github.robwin.swagger2markup.GroupBy;
import io.github.robwin.swagger2markup.Swagger2MarkupConverter;
import org.junit.After;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;
import springfox.documentation.staticdocs.SwaggerResultHandler;

import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
@RunWith(SpringRunner.class)
@SpringBootTest
public class DocumentationBuild {

    private String snippetDir = "target/asciidoc/generated-snippets";
    private String outputDir = "target/asciidoc";

    @Autowired
    private MockMvc mockMvc;

    @After
    public void Test() throws Exception {
        // 得到swagger.json,寫入outputDir目錄中
        mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))
                .andDo(SwaggerResultHandler.outputDirectory(outputDir).build())
                .andExpect(status().isOk())
                .andReturn();

        // 讀取上一步生成的swagger.json轉(zhuǎn)成asciiDoc,寫入到outputDir
        // 這個outputDir必須和插件里面標簽配置一致
        Swagger2MarkupConverter.from(outputDir + "/swagger.json")
                .withPathsGroupedBy(GroupBy.TAGS)// 按tag排序
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式
                .withExamples(snippetDir)
                .build()
                .intoFolder(outputDir);// 輸出
    }

    @Test
    public void TestApi() throws Exception {
        mockMvc.perform(get("/api/user/1")
                .accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andDo(MockMvcRestDocumentation.document("查詢用戶", preprocessResponse(prettyPrint())));

        UserInfo userInfo = new UserInfo();
        userInfo.setName("lisi");
        userInfo.setAge(23);
        userInfo.setAddress("山東濟南");
        userInfo.setSex("男");

        mockMvc.perform(post("/api/user").contentType(MediaType.APPLICATION_JSON)
                .content(JSON.toJSONString(userInfo))
                .accept(MediaType.APPLICATION_JSON))
                .andExpect(status().is2xxSuccessful())
                .andDo(MockMvcRestDocumentation.document("新增用戶", preprocessResponse(prettyPrint())));
    }


}

由于前面已經(jīng)配置了maven的插件，只需要執(zhí)行測試就可以生成相應(yīng)的文檔， 效果圖如下:

Swagger配置：

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket configSpringfoxDocket_all(ApiInfo apiInfo) {
        return new Docket(DocumentationType.SWAGGER_2)
                .produces(Sets.newHashSet("application/json"))
                .consumes(Sets.newHashSet("application/json"))
                .protocols(Sets.newHashSet("http", "https"))
                .apiInfo(apiInfo)
                .forCodeGeneration(true)
                .select().paths(regex("/api.*"))
                .build();
    }

    @Bean
    public Docket createUserInfoRestApi(ApiInfo apiInfo) {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("user")
                .produces(Sets.newHashSet("application/json"))
                .consumes(Sets.newHashSet("application/json"))
                .protocols(Sets.newHashSet("http", "https"))
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.sunxyz.controller"))
                .paths(regex("/api/user.*"))
                .build();
    }

    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Springfox REST API")
                .description("Descriptions.")
                .termsOfServiceUrl("http://springfox.io")
                .license("Apache License Version 2.0")
                .licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE")
                .version("2.0")
                .build();
    }

}

相關(guān)源碼已托管github

參考資料：

Spring REST Docs

SpringBoot項目生成RESTfull API的文檔

Introduction to Spring REST Docs

asciidoctor-maven-plugin