前言
同事說起接口文檔僞造的數據你們都保存到哪了?有說提交到測試用例的, 有說不想寫測試用例的, 還有說swagger的...好像想到了一個比swagger強大的東西
正文
以下爲轉載正文: https://blog.csdn.net/jcmj123456/article/details/110366809
JApiDocs是一個無需額外註解、開箱即用的SpringBoot接口文檔生成工具。
編寫和維護API文檔這個事情,對於後端程序員來說,是一件惱人但又不得不做的事情,我們都不喜歡寫文檔,但除非項目前後端代碼都是自己寫的,否則API文檔將是前後端協作中一個不可或缺的溝通界面。既然不可避免,那就想辦法弄個輪子吧。人生苦短,必須偷懶。
無圖無真相,生成文檔的效果如下:
相比Swagger要寫一堆註解,Spring RestDocs需要寫測試用例,才能生成API文檔。JApiDocs 具有無痛集成的特點,你只需花幾分鐘就能知道它怎麼用了。
快速開始
要使得JApiDcos正確工作,你寫的代碼應該是像下面的樣子的:
/** * 用戶接口 */ @RequestMapping("/api/user/") @RestController public class UserController { /** * 用戶列表 * @param listForm */ @RequestMapping(path = "list", method = {RequestMethod.GET, RequestMethod.POST} ) public ApiResult<PageResult<UserVO>> list(UserListForm listForm){ return null; } /** * 保存用戶 * @param userForm */ @PostMapping(path = "save") public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){ return null; } }
我們給Controller類和方法加上必要的註釋,給接口方法返回相關的對象類型。是的,這樣JApiDocs就能解析到相關的接口信息了,就跟我們平時寫的代碼是差不多的,但要注意,你要通過@param來告訴JApiDocs接口的參數,但在IDE的幫助下,這個工作將是輕鬆愉悅的:
然後你在任意一個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); // 執行生成文檔
接下來你只管好好寫代碼,生成Api文檔的工作就可以交給JApiDocs了,你不需要再爲額外編寫和維護文檔而煩惱。
功能特性
1、代碼即文檔
JApiDocs是通過直接解析SpringBoot的源碼語法來工作的,所以只要Controller的語法符合一定的代碼規範,有合理的註釋,就可以直接導出文檔。
2、支持導出HTML
便捷的導航和接口查看界面;可本地預覽,或者部署到HTTP服務器。推薦部署到服務器,方便前後端展開協作。
3、同步導出客戶端Model代碼
支持導出Android端的 Java 和iOS端的 Object C Model代碼,減少前端程序員的重複編碼工作。
4、更多特性
支持接口搜索;支持不同版本和英文文檔;自定義擴展等。
簡潔的文檔
再好用的東西,如果沒有文檔說明,別人也無從入手。爲了讓大家儘快上手,JApiDocs準備了一份極簡的文檔說明,確保你在幾分鐘就能用上JApiDocs。花5分鐘不到就能認識一個提高工作效率的工具,讓你把更多的時間花在更加有價值的事情上,你確認不看一下嗎?
倉庫地址:https://github.com/YeDaxia/JApiDocs
中文文檔:https://japidocs.agilestudio.cn/#/zh-cn/
PS:如果覺得我的分享不錯,歡迎大家隨手點贊、在看。