最近領導分了一個調研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