smart-doc 代碼逆向生成接口文檔

最近領導分了一個調研smart-doc的任務，可以掃描項目中Controller類，生成接口文檔，省去了人工手寫文檔的工作，而且隨時生成，便於維護；缺點就在於，要用這個第三方工具來限制規范代碼，例如方法、實體、控制層的注解編寫規范，增大項目負荷。

建議剛接觸的朋友根據場景，慎重考慮。

生成出來的文檔支持 html  markdown doc等格式，下面是HTML的

 

步驟1. idea加入自定義注解自動提示 @ignore,@required,@mock,@dubbo,@restApi,@order,@ignoreResponseBodyAdvice,@download,@page,@ignoreParams,@response,@date,@mapDto

 

步驟2：

這里說明一下，官方不推薦使用JUint生成方式，原因大概就是說，接口文檔是很多人維護，而每人本地的代碼不同，不同版本的代碼生成的文檔可能會內容不一致；

所以官方推薦，引用插件方式，掃描指定服務器下的jar，通過maven指令生成，本人沒有測試，可參照官方文檔

https://gitee.com/smart-doc-team/smart-doc/wikis/smart-doc%20maven%E6%8F%92%E4%BB%B6?sort_id=1791450

 

 上圖所示：

BuildApiDocTest  執行類

Constants 替換常量類

JsonBuildHelper 、 SpringBootDocBuildTemplate 可設置 ，覆蓋源代碼，實現一些定制化的標簽，填補原生smart-doc的不足（例如 ： 無法解析參數及返回值 帶Map類型的屬性）

注意：引入路徑必須遵循  package com.power.doc.helper; 和  package com.power.doc.template;

pom.xml

<dependency>
              <groupId>com.github.shalousun</groupId>
            <artifactId>smart-doc-maven-plugin</artifactId>
            <version>2.2.0</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

BuildApiDocTest

package com.foton.m2m.iov.fms.apidoc;

import java.util.Arrays;

import org.junit.Test;

import com.power.common.util.DateTimeUtil;
import com.power.doc.builder.ApiDocBuilder;
import com.power.doc.builder.HtmlApiDocBuilder;
import com.power.doc.constants.Constants;
import com.power.doc.model.ApiConfig;
import com.power.doc.model.ApiConstant;
import com.power.doc.model.RevisionLog;
import com.power.doc.model.SourceCodePath;

public class BuildApiDocTest {
    /**
     * 測試方法
     */
    @Test
    public void testBuilderControllersApiSimple() {
        ApiConfig config = new ApiConfig();
         // 嚴格模式
        config.setStrict(false);
        // 是否生成到一個文檔中
        config.setAllInOne(true);
        config.setMd5EncryptedHtmlName(false);
        
        config.setProjectName("車隊");
        // 文檔輸出地址
        config.setOutPath("e:\\smart-doc\\api\\fms");
        // 覆蓋文件
        config.setCoverOld(true);
        // 讀取項目源碼地址
        config.setSourceCodePaths(
//            // smart-doc對路徑自動會做處理，無論是window合適linux系統路徑，直接拷貝貼入即可。可以把該生成方法添加到具體項目中生成，也可以作為一個單獨項目。
            SourceCodePath.builder().setDesc("本項目代碼").setPath("src/main/java"),
            SourceCodePath.builder().setDesc("FMS-API").setPath("D:\\mywork\\iov-app\\platform-iov-fms\\api\\src\\main\\java"),
            SourceCodePath.builder().setDesc("COMMON-CORE").setPath("D:\\mywork\\framework\\platform-common-core\\api\\src\\main\\java")
        );
        
        config.setIgnoreRequestParams(Arrays.asList(
            "javax.servlet.http.HttpServletRequest",
            "javax.servlet.http.HttpServletResponse"
        ));
        config.setPackageFilters("");//掃描包的過濾器 controller包過濾，多個包用英文逗號隔開
        config.setRecursionLimit(5);//設置允許遞歸執行的次數用於避免一些對象解析卡主，默認是7，正常為3次以內，//@since smart-doc 1.8.8版本開始
        config.setRequestExample(false);//是否將請求示例展示在文檔中，默認true，@since smart-doc 1.9.0
        config.setResponseExample(true);//是否將響應示例展示在文檔中，默認為true，@since  smart-doc 1.9.0
        config.setDisplayActualType(false);//配置true會在注釋欄自動顯示泛型的真實類型短類名，@since 1.9.6
        config.setShowAuthor(false); //是否顯示接口作者名稱，默認是true,不想顯示可關閉
        ApiConstant apiConstant = new ApiConstant();
        apiConstant.setConstantsClass(Constants.class);
        config.setApiConstants(Arrays.asList(apiConstant));
       
        /*  設置枚舉字典
        config.setDataDictionaries(
                ApiDataDictionary.builder().setTitle("訂單字典").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc")
        );
        */
        //設置請求頭，如果沒有請求頭，可以不用設置
        /*   config.setRequestHeaders(
                   ApiReqHeader.header().setName("access_token").setType("string").setDesc("Basic auth credentials"),
                   ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key")
           );*/
        //非必須只有當setAllInOne設置為true時文檔變更記錄才生效，https://gitee.com/sunyurepository/ApplicationPower/issues/IPS4O
        config.setRevisionLogs(
                RevisionLog.builder().setRevisionTime("2021/05/08").setAuthor("Itink").setRemarks("第一版").setStatus("創建").setVersion("V1.2")
                //RevisionLog.builder().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("測試2").setStatus("修改").setVersion("V2.0")
        );
       
        long start = System.currentTimeMillis();
        // 生成adoc文件
        // AdocDocBuilder.builderControllersApi(config);
        // 生成md文件
        //ApiDocBuilder.buildApiDoc(config);
        // 生成html文件
        HtmlApiDocBuilder.buildApiDoc(config);
        long end = System.currentTimeMillis();
        DateTimeUtil.printRunTime(end, start);
    }
}

Constants

package com.foton.m2m.iov.fms.constants;

/**
 * 
 * @author hezhong 2021年7月7日
 */
public interface Constants {

    String FMS_ROOT_PATH = "/iov/fms";

    String FMS_API_ROOT_PATH = "/fmsapi";

    String FMS_ADMIN_ROOT_PATH = FMS_ROOT_PATH + "/admin";

    String SPRING_MVC_JSON_SUFFIX = ".json";

    String SPRING_MVC_HTML_SUFFIX = ".htm";
}

步驟3