本文主要分享一個基於個人興趣，旨在提高工作效率，開發了一個基於文檔註釋，接口文檔生成工具，歡迎大佬指點。

源碼以及使用demo地址：傳送門

1.前置介紹

1.1前世

現在大多數項目都走向了前後端分離，前後端並行開發，這就需要後端同學在開發前先寫好接口文檔。很多時候開發人員一般都會選擇，自己手寫文檔，或者使用目前開源的API工具，包括現在比較火的swagger但劣勢也不少

Swagger分析：
1).爲生成規範的接口文檔，需要添加各種各樣的註解，代碼侵入性太強；
2).增加了人工成本，做了多餘的事;
3).增加複雜度，代碼越多複雜性越差；
4).需要遵守其特殊的規範；

圖示示例：

1.2深思

問題：能不能根據參數類中的文檔註釋生成接口文檔呢？作爲程序員，代碼不應該即是文檔嗎？
那我們現在的需求是什麼呢？
1).代碼侵入性小，配置簡單、層級結構清晰、可輸出參數示例demo；
2).無需太複雜的功能，只要可以生成文檔即可；
3).最好是支持轉換成語雀，方便存檔；

帶着好奇心與興趣開始考慮？如何獲取文檔註釋？
遇到的最大難點就是：代碼編譯後會自動去除註釋；
從編譯後的代碼裏獲取肯定是行不通的。思維轉變，編譯後取不到，那就從未編譯的文件裏獲取。

1.3今生

根據文檔註釋生成接口文檔工具，在空餘時間研究並開發，已經基本完成分享使用。

主要用到的技術點

IO、反射、Freemarker模板引擎、Markdown語法

2.功能介紹

2.1主要功能

(1).讀取文檔註釋

讀取參數類中屬性文檔註釋；
讀取controller方法文檔註釋；
讀取接口類文檔註釋；

(2).支持複雜參數

參數層級嵌套，繼承父類；
支持返回值，泛型格式輸出（根據一些關鍵詞 T、Object、、等判斷的）；

(3).統一網關類接口文檔生成

支持生成統一網關接口的文檔，自定義@OpenApi註解的讀取；

(4).根據註解獲取請求類型

支持根據接口註解獲取請求類型，示例：@PostMapping；

(5).根據註解判斷參數是否非空

支持根據註解**[@NotBlank,@NotNull,@NotEmpty]**判斷入參是否必填，返回參數默認非空；

(6).根據註解判斷參數長度

支持根據註解**[@Max,@Min,@Size,@Length,@DecimalMax,@Range,@DecimalMin] **輸出入參長度；

(7).生成JSON示例

支持輸出json格式參數Demo示例；
支持根據類型以及名稱模擬值；

(8).生成統一結構MD接口文檔

生成MD接口文檔；
支持拷貝到語雀平臺，文檔格式依然存在；

(9).文檔參數類型轉換

支持參數駝峯轉下劃線轉換 ;

(10).排序規則

參數屬性排序 > 以類中屬性從上往下順序排序；
接口方法排序 > 以類中方法從上往下順序排序；

2.2.優缺點

優點:
(1).代碼非侵入性，無需添加一些無用的註解；
(2).無需引入依賴生成，減少與業務項目耦合度；
(3).可以自定義一些功能；
(4).早日實現代碼即文檔的期盼，減少人工編寫接口文檔的時間；

缺點：
(1).返回參數多級需要使用泛型；
(2).拷貝到語雀後樣式兼容差強人意；

2.3.示例圖

3.特殊規則

** 注：未按照如下規則，可能會導致無法生成完整文檔或失敗。**

3.1參數類文檔註釋匹配-特殊規則
(1).內部類支持不太完善；

3.2Controller接口方法類規則
(1).返回值支持自定義類，統一返回Response,需要加泛型，否則獲取不到嵌套的返回值，示例：Response ;
(2).同一個controller類方法名稱建議不相同，重名情況下可能會導致方法註釋匹配錯誤問題 ;
(3).java.包下的返回值暫不支持 ;
(4).private方法會自動過濾 ;
(5).相同方法名，重載的方法，可能會出現註釋匹配錯誤 ;

4.使用方式

文檔生成的是md文件支持Markdown語法
目前支持兩種使用方式，
方式一：外置工具方式
方式二：依賴jar包+啓動類方式
兩種方式功能一致，可選擇性使用。推薦使用侵入性較小的外置工具方式。

4.1外置工具生成

注：外置工具生成，指的是無需引入工具jar包方式生成

4.1.1精簡版使用示例

1).下載工具包

源碼地址

注意：下載後解壓路徑，最好不要有中文路徑

可執行jar解壓後文件示例

文件介紹

ApiGeneratorConfig.xml > 當前配置文件
ApiGeneratorConfig_orgin.xml > 全配置文件
api-document-generate.jar > 生成工具Jar
start.bat > Win 系統下啓動
start.command > ios 系統下啓動

下載完工具後，可打開源碼可執行jar目錄下ApiGeneratorConfig.xml配置成相應的自己電腦的示例工程目錄即可開始生成

2).配置ApiGeneratorConfig.XML

<?xml version="1.0" encoding="UTF-8" ?>
<config>
    <!-- 生成類型 1-根據包地址生成，包下所有類的接口 2-自定義類生成 -->
    <generateType value="1"/>

    <!-- 項目下類掃描路徑（絕對路徑）, 支持多個 , 一般是項目根路徑 -->
    <projectScanPaths>
        <path value="/Users/xx/project/api-generate-demo"/>
    </projectScanPaths>

    <!-- 包文件夾地址（絕對路徑,生成類型爲1時必填） -->
    <apiPackagePath
            value="/Users/xx/project/api-generate-demo/api-generate-web02/src/main/java/com/example/controller"/>

    <!-- 類文件地址（絕對路徑,生成類型爲2時必填）-->
    <apiClassPaths>
        <path value=""/>
    </apiClassPaths>

</config>

啓動注意事項

啓動前需要配置好XML文件中的內容；
配置文件獲取路徑默認是當前運行路徑下名稱爲 ApiGeneratorConfig.xml；
生成文件默認地址：當前運行路徑下 generate 文件夾下；

Win 系統下啓動雙擊 start.bat
ios 系統下啓動雙擊 start.command

4.1.2全功能配置指南

1).根據包地址生成

<?xml version="1.0" encoding="UTF-8" ?>
<config>
    <!-- 生成類型 1-根據包地址生成，包下所有類的接口 2-自定義類生成 -->
    <generateType value="1"/>

    <!-- 項目下類掃描路徑（絕對路徑）, 支持多個 -->
    <projectScanPaths>
        <path value="/Users/xx/project/api-generate-demo"/>
    </projectScanPaths>

    <!-- 包文件夾地址（絕對路徑,生成類型爲1時必填） -->
    <apiPackagePath
            value="/Users/xx/project/api-generate-demo/api-generate-web02/src/main/java/com/example/controller"/>

</config>

2).根據類地址生成

<?xml version="1.0" encoding="UTF-8" ?>
<config>
    <!-- 生成類型 1-根據包地址生成，包下所有類的接口 2-自定義類生成 -->
    <generateType value="2"/>

    <!-- 項目下類掃描路徑（絕對路徑）, 支持多個 -->
    <projectScanPaths>
        <path value="/Users/xx/project/workproject/fshows-finance"/>
    </projectScanPaths>

    <!-- 類文件地址（絕對路徑,生成類型爲2時必填）-->
    <apiClassPaths>
        <path value="/Users/xx/project/workproject/fshows-finance/fshows-finance-openapi/src/main/java/com/fshows/finance/service/FeeCodeApiService.java"/>
        <path value="/Users/xx/project/workproject/fshows-finance/fshows-finance-openapi/src/main/java/com/fshows/finance/service/PayableApiService.java"/>
    </apiClassPaths>
</config>

3).統一網關類型接口配置

<!-- 開放接口註解類配置, annotationFieldName 默認 "method" -->
<gateWayField annotationName="com.fshows.finance.common.annotation.OpenApi" annotationFieldName="method"/>

4).根據參數名排除

<!-- 排除參數名配置（支持多個） -->
<apiExcludeParamNames>
  <paramName value="nonce"/>
  <paramName value="sourceType"/>
</apiExcludeParamNames>

5).根據參數全路徑排除

  <!-- 排除參數全類名配置（支持多個） -->
    <apiExcludeParamClassNames>
        <paramClassName value="com.demo.param.UserLoginResult"/>
    </apiExcludeParamClassNames>

6).Json示例生成開關

<!-- 是否生成 1-是,2-否 默認1 -->
<generateJsonFlag value="2"/>

7).參數類型轉換

<!-- 參數類型 1-默認,2-駝峯轉下劃線 -->
<apiParamType value="2"/>

8).生成文件路徑配置

注：生成文件默認名稱，Api-generate-MMddHHmmss.md
默認路徑是當前項目路徑,路徑可自定義

<!-- 生成文件地址(默認：當前目錄) -->
<generateFilePath value="/Users/mengqiang/Desktop/api-generate-tool/finance/openapi"/>

9).項目請求地址根路徑

<!-- 項目接口訪問根路徑 默認無 -->
<projectRootUrl value=""/>

10).自定義統一返回對象

注：一些接口中未包含統一返回對象，但是希望生成的文檔包含此結構
參數含義依次爲：參數名, 參數類型, 參數描述, 是否作爲父級
是否作爲父級標識爲是情況下將會，把原先的返回參數添加到該父級下

<!-- 自定義頂級返回對象屬性 -->
<apiRootResField>
  <field name="success" typeClassName="java.lang.Boolean" desc="請求是否成功" isParent="0"/>
  <field name="data" typeClassName="java.lang.Object" desc="" isParent="1"/>
  <field name="errorCode" typeClassName="java.lang.String" desc="錯誤碼" isParent="0"/>
  <field name="errorMsg" typeClassName="java.lang.String" desc="錯誤信息" isParent="0"/>
</apiRootResField>

11).接口頭信息輸出

針對接口文檔存在統一頭信息情況下使用，可以在每一個接口中添加頭信息參數

<!-- 請求 contentType -->
<contentType value="application/x-www-form-urlencoded"/>

<!-- 頭信息 -->
<apiHeaderField>
  <field name="token" type="String" desc="當前登錄用戶token" isRequired="1"/>
</apiHeaderField>

5.文件查看

5.1.[推薦]打開工具

系統	工具名稱	官網地址
Windows	Typora	https://www.typora.io/
IOS	MacDown	https://macdown.uranusjr.com/

Demo示例圖：

4.2.2.文本形式查看

支持以文本形式打開文件，直接拷貝內容粘貼到語雀文檔中

注：輸出使用的是Markdown 語法，若拷貝到語雀粘貼時請點擊進行轉換，
建議採用工具打開後，再拷貝到羽雀，
使用文本格式拷貝到語雀後會被重新編譯，內容會存在多餘的空行。**

轉換後示例：

6.附言

萬物有痕，可能會有一些未考慮到場景或問題，歡迎大佬指點。

公衆號
更多精彩內容、編程故事、心得分享，歡迎關注公衆號

基於文檔註釋接口文檔生成工具(代碼0侵入附源碼)