# JApiDocs教程 ## 前言 - 作為一名優秀的程式設計師來說，由於涉及到要與前端進行對接，所以避免不了的就是寫介面文件。寫完介面文件，一旦程式碼返回結果，引數等出現變動，介面文件還得隨之改動，十分麻煩，違背了我們簡單，快速，低bug的開發初衷。 - 所以，自動生成介面文件的工具就出現了。大家最熟悉的應該就是swagger了，我並沒有使用過swagger，雖然它比較健壯，穩定。但是由於它的規範很複雜，需要將程式碼變動的地方也很多。所以我使用了JApiDocs這個工具來為我的專案自定生成介面文件。 - 它的優點就是，相對於springboot以及ssm開發模式而言，它的改動都不是很大，規範一下程式碼，就可以輕鬆獲取介面文件了。 - 問題：引數為實體類物件時，直接顯示物件裡的所有欄位。而真正使用的欄位只有一部分。大體沒什麼毛病，介面也很簡潔美觀。大家如果有解決引數精準顯示的想法，可以在評論區一起討論下。 ## 一、Maven依賴 ``` io.github.yedaxia japidocs 1.4.3 ``` ## 二、程式碼規範 為什麼要進行程式碼規範？ - JApiDocs會根據固定的格式，來為我們解析出相應的介面文件，相對比與swagger來說，JApiDocs的格式相對來說是很簡單的，springboot開發的專案使用起來改動不大，同時還能使我們的程式碼規範，簡潔，一致。所以我們只要遵循以下幾點就能得到規整的介面文件了。 以下都是針對於controller模組： ### 1. 分組名稱 @description *注：官方文件中註明分組名稱@description，但是實際應用中不需要加入註解，像下例所示，直接寫註釋即可。（類上寫不寫都行，方法上如果加上@description反而不顯示）* 例： ``` /** * 使用者介面 */ /*注意：這裡不能空行，否則註釋名無法顯示*/ @RequestMapping("test") @Controller public class testInterface { @Autowired private RoleService roleService; /** * 儲存使用者 */ @PostMapping("advice") public RoleInfo getAdviceList(String docId){ return roleService.FindRoleBydocId(docId); } } ``` 效果圖：  ### 2. 介面引數（JApiDocs 會通過 @param 來尋找介面引數和進一步解析引數的內容） *注：註釋一定要放在@註解的上面，否則引數會不顯示* #### （1）格式：介面引數 @param 欄位 欄位解釋 例： ``` /** * @description 儲存使用者 * @param docId 醫生id */ @PostMapping("advice") public RoleInfo getAdviceList(String docId){ return roleService.FindRoleBydocId(docId); } ``` 效果圖：  #### （2）在相應的bean物件裡添加註釋 例： ``` public class RemindInfo implements Serializable { private long remindId; //提醒id private String remindContent; //提醒資訊 private java.sql.Timestamp remindTime; //提醒時間 } ``` 效果圖：  *注：欄位後的註釋一定都要寫上，否則會報下面的錯誤：*  #### （3）使用@RequestBody 註解json格式的引數 效果圖：  ### 3. 返回物件 #### （1）@RestController 或 @ResponseBody 返回json資料型別 例： ``` /** * 使用者介面 */ @RequestMapping("/test") @RestController public class testInterface { @Autowired private RoleService roleService; /** * 儲存使用者 * @param docId 醫生id */ @ApiDoc @PostMapping("advice") public RoleInfo getAdviceList(String docId){ return roleService.FindRoleBydocId(docId); } } ``` 效果圖：  #### （2）請求型別 ``` @PostMapping("advice")/@GetMapping("advice") public RoleInfo getAdviceList(String docId){ return roleService.FindRoleBydocId(docId); } ``` 效果圖：   沒有指定具體型別時： 注：返回引數不能指向不明，如：Object，否則會報 Exception in thread "main" io.github.yedaxia.apidocs.exception.JavaFileNotFoundException: Cannot find java file 的錯誤。 ### 4、高階配置 #### （1）@ApiDoc ##### a.實現 JApiDocs 預設只匯出聲明瞭@ApiDoc的介面，我們前面通過設定config.setAutoGenerate(Boolean.TRUE) 來解除了這個限制。如果你不希望把所有的介面都匯出，你可以把autoGenerate設定關閉，在相關Controller類或者介面方法上通過新增@ApiDoc來確定哪些介面需要匯出。 ##### b.其他設定 result: 這個可以直接宣告返回的物件型別，如果你聲明瞭，將會覆蓋SpringBoot的返回物件 stringResult：返回字串，在返回結果比較簡單，而不想建立一個專門的返回類，則可以考慮使用這個屬性。 url: 請求URL，擴充套件欄位，用於支援非SpringBoot專案 method: 請求方法，擴充套件欄位，用於支援非SpringBoot專案 例： ``` @ApiDoc(result = AdminVO.class, url = "/api/v1/admin/login2", method = "post") ``` ``` stringResult 例項，在文件中將會自動格式化json字串： @ApiDoc(stringResult = "{code: 0, data: 'success'}") @GetMapping(value = "custom-json") public Map customJsonResult(){} ``` ### (2)@Ignore (忽略Controller，介面，欄位) 例：忽略Controller ``` @Ignore public class UserController { } ``` ## 三、配置引數 在任意一個main入口執行下面的程式碼： ``` DocsConfig config = new DocsConfig(); config.setProjectPath("your springboot project path"); // 專案根目錄 config.setProjectName("ProjectName"); // 專案名稱 config.setApiVersion("V1.0"); // 宣告該API的版本 config.setDocsPath("your api docs path"); // 生成API 文件所在目錄 config.setAutoGenerate(Boolean.TRUE); // 配置自動生成 Docs.buildHtmlDocs(config); // 執行生成文件 ``` 執行結果類似效果圖：  ## 四、匯出格式 ### （1）Markdown ``` config.addPlugin(new MarkdownDocPlugin()); ``` ### （2）匯出 pdf 或者 word 可以通過 [pandoc](https://pandoc.org/) 把 markdown 格式轉成 pdf 或者 word 格式。 ## 五、自定義程式碼模板 JApiDocs 除了支援文件匯出，目前也支援生成了 Android 和 iOS 的返回物件程式碼，對應 Java 和 Object-C 語言， 如果你想修改程式碼模板，可以通過以下的方法： ### （1）定義程式碼模板 把原始碼中library專案resources目錄下的程式碼模板拷貝一份，其中，IOS_表示 Object-C 程式碼模板，JAVA_開頭表示 Java程式碼， 模板中類似${CLASS_NAME}的符號是替換變數，具體含義你可以結合生成的程式碼進行理解，然後按照你想要的程式碼模板進行修改即可。 ### （2）選擇新的模板 通過DocsConfig配置模板路徑替換成新的模板： ``` docsConfig.setResourcePath("模板路徑"); ``` ## 六、新增更多功能 JApiDocs 提供了外掛介面，你可以通過外掛介面來實現更多豐富的功能，下面介紹如何新增外掛： ### （1）實現 IPluginSupport 介面 ``` public class CustomPlugin implements IPluginSupport{ @Override public void execute(List controllerNodeList){ // 實現你自己的功能需求 } } ``` ### （2）新增外掛 ``` config.addPlugin(new CustomPlugin()); ``` ## 七、問題的解決 ### 1、如何排查錯誤？ 關閉自動生成config.setAutoGenerate(Boolean.FALSE)，使用@ApiDoc 來一個個介面匯出排查問題。 ### 2、多模組找不到相關類原始碼？ 如果原始碼路徑沒有全部識別出來，可以通過config.addJavaSrcPath來新增模組的原始碼路徑，注意要新增到src/main/java這一級。 ## 八、自定義註釋模板 這是我針對JApiDocs，對我的模板進行了一定的調整，以方便對JApiDocs的使用，大家可以參考一下。 ### （1）Live Templates ``` /** * TODO * @create_by: 作者名字 * @create_time: $date$ $time$ * $params$ * @return $return$ */ ``` ### （2）File Header ``` /** * @Author 作者名字 * @Date ${DATE} ${TIME} * @description ${description} * @Version 1.0 */ ``` 具體如何實現自定義方法註釋，類註釋。可以參考下面的文章： > https://blog.csdn.net/qq_38675373/article/details/105886922 JApiDocs官方文件地址： > https://japidocs.agilestudio.cn/#/