Tips：喜歡的話可以關(guān)注小萌哦~~~

今天小萌給大家推薦的一個(gè)開(kāi)源Java Restful API 文檔生成工具，一加【oneplus】、iflytek都在用。所以，自然差不了。

官方簡(jiǎn)介

smart-doc 是一個(gè) java restful api 文檔生成工具，smart-doc 顛覆了傳統(tǒng)類(lèi)似 swagger 這種大量采用注解侵入來(lái)生成文檔的實(shí)現(xiàn)方法。 smart-doc 完全基于接口源碼分析來(lái)生成接口文檔，完全做到零注解侵入，你只需要按照java標(biāo)準(zhǔn)注釋的寫(xiě)，smart-doc 就能幫你生成一個(gè)簡(jiǎn)易明了的 Markdown、Html、AsciiDoc 文檔。

如果你已經(jīng)厭倦了 swagger 等文檔工具的無(wú)數(shù)注解和強(qiáng)侵入污染，smart-doc是不錯(cuò)的選擇！

最新版本

smart-doc 1.7.7

• 修改timestamp類(lèi)型字段創(chuàng)建json示例錯(cuò)誤bug。
• fix #I1545A 單接口多路徑bug。
• 修改部分url生成部署空格問(wèn)題。
• 優(yōu)化對(duì)java.util.concurrent.ConcurrentMap的解析。

開(kāi)源地址

https://gitee.com/sunyurepository/smart-doc

快速入門(mén)

1、Getting started

https://gitee.com/sunyurepository/api-doc-test.git

你可以啟動(dòng)這個(gè)Spring Boot的項(xiàng)目，然后訪問(wèn)http://localhost:8080/doc/api.html來(lái)瀏覽smart-doc生成的接口文檔。

2、Dependency

<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc</artifactId>
    <version>1.7.7</version>
    <scope>test</scope>
</dependency>

3、Create a unit test

通過(guò)運(yùn)行一個(gè)單元測(cè)試來(lái)讓Smart-doc為你生成一個(gè)簡(jiǎn)潔明了的api文檔。

public class ApiDocTest {

    /**
     * 包括設(shè)置請(qǐng)求頭，缺失注釋的字段批量在文檔生成期使用定義好的注釋
     */
    @Test
    public void testBuilderControllersApi() {
        ApiConfig config = new ApiConfig();
        config.setServerUrl("http://localhost:8080");
        //true會(huì)嚴(yán)格要求注釋?zhuān)扑]設(shè)置true
        config.setStrict(true);
        //true會(huì)將文檔合并導(dǎo)出到一個(gè)markdown
        config.setAllInOne(false);
        //生成html時(shí)加密文檔名不暴露controller的名稱(chēng)
        config.setMd5EncryptedHtmlName(true);

        //指定文檔輸出路徑
        //@since 1.7 版本開(kāi)始，選擇生成靜態(tài)html doc文檔可使用該路徑：DocGlobalConstants.HTML_DOC_OUT_PATH;
        config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);
        // @since 1.2,如果不配置該選項(xiàng)，則默認(rèn)匹配全部的controller,
        // 如果需要配置有多個(gè)controller可以使用逗號(hào)隔開(kāi)
        config.setPackageFilters("com.power.doc.controller");
        //不指定SourcePaths默認(rèn)加載代碼為項(xiàng)目src/main/java下的,如果項(xiàng)目的某一些實(shí)體來(lái)自外部代碼可以一起加載
        config.setSourceCodePaths(
                //自1.7.0版本開(kāi)始，在此處可以不設(shè)置本地代碼路徑，單獨(dú)添加外部代碼路徑即可
//            SourceCodePath.path().setDesc("本項(xiàng)目代碼").setPath("src/main/java"),
            SourceCodePath.path().setDesc("加載項(xiàng)目外代碼").setPath("E:\\ApplicationPower\\ApplicationPower\\Common-util\\src\\main\\java")
        );
        //since 1.7.5
        //如果該選項(xiàng)的值為false,則smart-doc生成allInOne.md文件的名稱(chēng)會(huì)自動(dòng)添加版本號(hào)
        config.setCoverOld(true);
        //since 1.7.5
        //設(shè)置項(xiàng)目名(非必須)，如果不設(shè)置會(huì)導(dǎo)致在使用一些自動(dòng)添加標(biāo)題序號(hào)的工具顯示的序號(hào)不正常
        config.setProjectName("搶購(gòu)系統(tǒng)");
        //設(shè)置請(qǐng)求頭，如果沒(méi)有請(qǐng)求頭，可以不用設(shè)置
        config.setRequestHeaders(
                ApiReqHeader.header().setName("access_token").setType("string").setDesc("Basic auth credentials"),
                ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key")
        );
        //對(duì)于外部jar的類(lèi)，編譯后注釋會(huì)被擦除，無(wú)法獲取注釋?zhuān)侨绻勘容^多請(qǐng)使用setSourcePaths來(lái)加載外部代碼
        //如果有這種場(chǎng)景，則自己添加字段和注釋?zhuān)琣pi-doc后期遇到同名字段則直接給相應(yīng)字段加注釋
        config.setCustomResponseFields(
                CustomRespField.field().setName("success").setDesc("成功返回true,失敗返回false"),
                CustomRespField.field().setName("message").setDesc("接口響應(yīng)信息"),
                CustomRespField.field().setName("data").setDesc("接口響應(yīng)數(shù)據(jù)"),
                CustomRespField.field().setName("code").setValue("00000").setDesc("響應(yīng)代碼")
        );

        //設(shè)置項(xiàng)目錯(cuò)誤碼列表，設(shè)置自動(dòng)生成錯(cuò)誤列表,
        List<ApiErrorCode> errorCodeList = new ArrayList<>();
        for (ErrorCodeEnum codeEnum : ErrorCodeEnum.values()) {
            ApiErrorCode errorCode = new ApiErrorCode();
            errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getDesc());
            errorCodeList.add(errorCode);
        }
        //如果沒(méi)需要可以不設(shè)置
        config.setErrorCodes(errorCodeList);

        //非必須只有當(dāng)setAllInOne設(shè)置為true時(shí)文檔變更記錄才生效，https://gitee.com/sunyurepository/ApplicationPower/issues/IPS4O
        config.setRevisionLogs(
                RevisionLog.getLog().setRevisionTime("2018/12/15").setAuthor("chen").setRemarks("測(cè)試").setStatus("創(chuàng)建").setVersion("V1.0"),
                RevisionLog.getLog().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("測(cè)試2").setStatus("修改").setVersion("V2.0")
        );
        
        //since 1.7.5
        //文檔添加數(shù)據(jù)字典
        config.setDataDictionaries(
            ApiDataDictionary.dict().setTitle("訂單狀態(tài)").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc"),
            ApiDataDictionary.dict().setTitle("訂單狀態(tài)1").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc")
        );


        long start = System.currentTimeMillis();
        ApiDocBuilder.builderControllersApi(config);

        //@since 1.7+版本開(kāi)始，smart-doc支持生成帶書(shū)簽的html文檔，html文檔可選擇下面額方式
        //HtmlApiDocBuilder.builderControllersApi(config);
        //@since 1.7+版本開(kāi)始，smart-doc支撐生成AsciiDoc文檔，你可以把AsciiDoc轉(zhuǎn)成HTML5的格式。
        //@see https://gitee.com/sunyurepository/api-doc-test
        //AdocDocBuilder.builderControllersApi(config);
                
        long end = System.currentTimeMillis();
        DateTimeUtil.printRunTime(end, start);
    }
}

4、接口頭部效果圖

Java 零注解文檔生成工具—smart-doc，看完有替換swagger的沖動(dòng)

5、請(qǐng)求參數(shù)示例效果圖

Java 零注解文檔生成工具—smart-doc，看完有替換swagger的沖動(dòng)

6、響應(yīng)參數(shù)示例效果圖

Java 零注解文檔生成工具—smart-doc，看完有替換swagger的沖動(dòng)

給使用者的建議

• smart-doc雖然可以關(guān)閉注解檢測(cè)，好的規(guī)范更容易讓項(xiàng)目變得更容易維護(hù)* smart-doc的出發(fā)的目標(biāo)不是僅僅為書(shū)寫(xiě)接口的開(kāi)發(fā)人員自己測(cè)試接口服務(wù)的，而是希望導(dǎo)出的文檔能夠用極少的變更就能做接口服務(wù)對(duì)接文檔。* smart-doc主要目的是為了減少接口文檔書(shū)寫(xiě)和造測(cè)試模擬數(shù)據(jù)* smart-doc拉取了大量的開(kāi)源項(xiàng)目做了源碼解析測(cè)試，開(kāi)發(fā)過(guò)程中也做了很多實(shí)際場(chǎng)景的思考，工具開(kāi)源的目的不是做著玩，而是想幫助大家解決問(wèn)題。

評(píng)價(jià)

看過(guò)示例之后是不是想要有替換swagger的沖動(dòng)？別著急，swagger雖然耦合很?chē)?yán)重，但是這個(gè)也直接避免了一些懶惰的開(kāi)發(fā)人員改接口不改注釋的習(xí)慣。

Java 零注解文檔生成工具—smart-doc，看完有替換swagger的沖動(dòng)