Spring Boot [如何優(yōu)雅的編寫(xiě)文檔]

曹金海發(fā)布于2019-08-16 10:33 / 1233人閱讀

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

導(dǎo)讀：

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

關(guān)于swagger：

Swagger - 前后端分離后的契約

通過(guò)Swagger進(jìn)行API設(shè)計(jì)，與Tony Tam的一次對(duì)話

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

編寫(xiě)離線文檔：

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

這就是今天的主角：Springfox和Spring Rest Docs幫我們做的事情
1.預(yù)備知識(shí)：
建議了解swagger、Asciidoc、asciidoctor-maven-plugin和SpringBoot Testing。對(duì)應(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自動(dòng)生成文檔。

引入pom依賴(lài)：

其實(shí)我們的思路就是把swagger在線文檔轉(zhuǎn)成staticdocs形式的文檔，引入相關(guān)的一些依賴(lài) Spring Rest Docs的依賴(lài)spring-restdocs-mockmvc，離線文檔的依賴(lài)springfox-staticdocs，因?yàn)橐趩卧獪y(cè)試的時(shí)候生成文檔，所以再加測(cè)試相關(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

使用Maven插件：

我們使用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

編寫(xiě)測(cè)試類(lèi)生成離線文檔：

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,寫(xiě)入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,寫(xiě)入到outputDir
        // 這個(gè)outputDir必須和插件里面標(biāo)簽配置一致
        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("查詢(xún)用戶(hù)", preprocessResponse(prettyPrint())));

        UserInfo userInfo = new UserInfo();
        userInfo.setName("lisi");
        userInfo.setAge(23);
        userInfo.setAddress("山東濟(jì)南");
        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("新增用戶(hù)", preprocessResponse(prettyPrint())));
    }


}

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

補(bǔ)充：

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項(xiàng)目生成RESTfull API的文檔

Introduction to Spring REST Docs

asciidoctor-maven-plugin