還在用絲襪哥(Swagger)做API文件?快來看看這款幫你減少百分之九十工作量的開源工具!

語言: CN / TW / HK

theme: channing-cyan

「這是我參與2022首次更文挑戰的第5天,活動詳情檢視:2022首次更文挑戰

提一嘴Swagger

    相信不少的小夥伴都會在日常工作中寫API文件,確實這個文件很有必要去寫,便於專案的維護,在我們提桶的時候,接盤俠可以輕鬆地接管我們的專案。說起API文件,我們腦海中想到的就是肯定是Swagger,他以前確實統治了江湖很久,因為他的確很方便,也很智慧,但是吧,你寫多了總感覺哪裡不對勁,是的,他的程式碼侵入性太強,而且要寫大量重複的註釋,那我最近在寫的一個專案來說,簡直是程式設計師的夢魘。 在這裡插入圖片描述     這只是一個實體類的一部分,還有service、controller的這些註解我就不一一列舉了,侵入性太強,註釋繁多,而且你在編譯以後還是存在於程式碼中不會被擦除。     於是乎,我有一次在寫程式碼(摸魚)的時候,偶然發現一個Gitee上的高贊API文件,連結:smart-doc 在這裡插入圖片描述

主角smart-doc

    smart-doc是一款同時支援JAVA REST API和Apache Dubbo RPC介面文件生成的工具,劃重點了,他還支援Dubbo RPC介面文件,遙想當年,Swagger要想支援Dubbo的話必須要自己修改和拓展,官方是不支援的。於是我就照著官方文件給的案例,去部署生成了一下API文件,真香!

新建smart-doc.json

    我們需要新建一個smart-doc.json來寫一些配置,我這裡也給出一份模板,有需要的鐵汁們直接cv改改即可。 json { //伺服器地址 "serverUrl": "http://127.0.0.1", //是否用嚴格模式,嚴格模式強制檢查註釋 "isStrict": false, //所有介面文件合併生成到一個文件 "allInOne": true, //文件的輸出路徑 "outPath": "src/main/resources/static/doc", //指定專案名稱,用於顯示在文件中 "projectName": "test-smart-doc" }

引入依賴

xml <plugin> <groupId>com.github.shalousun</groupId> <artifactId>smart-doc-maven-plugin</artifactId> <version>2.2.2</version> <configuration> <!--指定生成文件使用的配置檔案--> <configFile>./src/main/resources/smart-doc.json</configFile> </configuration> <executions> <execution> <!--不需要在編譯專案時自動生成文件可註釋phase--> <phase>compile</phase> <goals> <goal>html</goal> </goals> </execution> </executions> </plugin> ## 測試 在這裡插入圖片描述     雙擊smart-doc即可生成java普通(為了區別於Dubbo)的文件,他的UI介面也不醜,大致長這樣。 在這裡插入圖片描述     我們幾乎沒有寫任何註釋程式碼,就自動生成了一個API文件,沒有任何侵入性。

smart-doc強在哪?

    smart-doc對比傳統一哥Swagger究竟有什麼不同? 1. smart-doc主要是基於原始碼和JAVADOC標註註釋來生成文件,是在開發期或者是專案的編譯期執行生成文件,意味著你是在專案編譯完以後你在原始碼裡面是找不到smart-doc的任何依賴的,0侵入性。 2. swagger主要原理是利用JAVA的註解和反射機制去生成文件,這種方式侵入性太強。

    這也就是為什麼我剛剛什麼註解都沒寫,但是依然可以生成合格的API文件,於是乎我馬上把Swagger換成了smart-doc,只能說真香,再也不用寫@ApiModel這種註解了。