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這種註解了。