Java 零註解文檔生成工具—smart-doc，看完有替換swagger的衝動

Tips：喜歡的話可以關注小萌哦~~~

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

官方簡介

smart-doc 是一個 java restful api 文檔生成工具，smart-doc 顛覆了傳統類似 swagger 這種大量採用註解侵入來生成文檔的實現方法。 smart-doc 完全基於接口源碼分析來生成接口文檔，完全做到零註解侵入，你只需要按照java標準註釋的寫，smart-doc 就能幫你生成一個簡易明瞭的 Markdown、Html、AsciiDoc 文檔。

如果你已經厭倦了 swagger 等文檔工具的無數註解和強侵入污染，smart-doc是不錯的選擇！

最新版本

smart-doc 1.7.7

• 修改timestamp類型字段創建json示例錯誤bug。
• fix #I1545A 單接口多路徑bug。
• 修改部分url生成部署空格問題。
• 優化對java.util.concurrent.ConcurrentMap的解析。

開源地址

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

快速入門

1、Getting started

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

你可以啓動這個Spring Boot的項目，然後訪問http://localhost:8080/doc/api.html來瀏覽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

通過運行一個單元測試來讓Smart-doc爲你生成一個簡潔明瞭的api文檔。

public class ApiDocTest {

    /**
     * 包括設置請求頭，缺失註釋的字段批量在文檔生成期使用定義好的註釋
     */
    @Test
    public void testBuilderControllersApi() {
        ApiConfig config = new ApiConfig();
        config.setServerUrl("http://localhost:8080");
        //true會嚴格要求註釋，推薦設置true
        config.setStrict(true);
        //true會將文檔合併導出到一個markdown
        config.setAllInOne(false);
        //生成html時加密文檔名不暴露controller的名稱
        config.setMd5EncryptedHtmlName(true);

        //指定文檔輸出路徑
        //@since 1.7 版本開始，選擇生成靜態html doc文檔可使用該路徑：DocGlobalConstants.HTML_DOC_OUT_PATH;
        config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);
        // @since 1.2,如果不配置該選項，則默認匹配全部的controller,
        // 如果需要配置有多個controller可以使用逗號隔開
        config.setPackageFilters("com.power.doc.controller");
        //不指定SourcePaths默認加載代碼爲項目src/main/java下的,如果項目的某一些實體來自外部代碼可以一起加載
        config.setSourceCodePaths(
                //自1.7.0版本開始，在此處可以不設置本地代碼路徑，單獨添加外部代碼路徑即可
//            SourceCodePath.path().setDesc("本項目代碼").setPath("src/main/java"),
            SourceCodePath.path().setDesc("加載項目外代碼").setPath("E:\\ApplicationPower\\ApplicationPower\\Common-util\\src\\main\\java")
        );
        //since 1.7.5
        //如果該選項的值爲false,則smart-doc生成allInOne.md文件的名稱會自動添加版本號
        config.setCoverOld(true);
        //since 1.7.5
        //設置項目名(非必須)，如果不設置會導致在使用一些自動添加標題序號的工具顯示的序號不正常
        config.setProjectName("搶購系統");
        //設置請求頭，如果沒有請求頭，可以不用設置
        config.setRequestHeaders(
                ApiReqHeader.header().setName("access_token").setType("string").setDesc("Basic auth credentials"),
                ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key")
        );
        //對於外部jar的類，編譯後註釋會被擦除，無法獲取註釋，但是如果量比較多請使用setSourcePaths來加載外部代碼
        //如果有這種場景，則自己添加字段和註釋，api-doc後期遇到同名字段則直接給相應字段加註釋
        config.setCustomResponseFields(
                CustomRespField.field().setName("success").setDesc("成功返回true,失敗返回false"),
                CustomRespField.field().setName("message").setDesc("接口響應信息"),
                CustomRespField.field().setName("data").setDesc("接口響應數據"),
                CustomRespField.field().setName("code").setValue("00000").setDesc("響應代碼")
        );

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

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


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

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

4、接口頭部效果圖

5、請求參數示例效果圖

6、響應參數示例效果圖

給使用者的建議

• smart-doc雖然可以關閉註解檢測，好的規範更容易讓項目變得更容易維護* smart-doc的出發的目標不是僅僅爲書寫接口的開發人員自己測試接口服務的，而是希望導出的文檔能夠用極少的變更就能做接口服務對接文檔。* smart-doc主要目的是爲了減少接口文檔書寫和造測試模擬數據* smart-doc拉取了大量的開源項目做了源碼解析測試，開發過程中也做了很多實際場景的思考，工具開源的目的不是做着玩，而是想幫助大家解決問題。

評價

看過示例之後是不是想要有替換swagger的衝動？彆着急，swagger雖然耦合很嚴重，但是這個也直接避免了一些懶惰的開發人員改接口不改註釋的習慣。