手寫Swagger註解、JavaDoc一鍵生成外掛程式，生產力拉滿~

2024-07-05碼農

下面是一個普通的 Request 類，先簡單的看一下：

/** * TestRequest desc */ @Data @Slf4j public classTestRequest{ private String name; private Integer age; private Address address; /** * address desc */ @Setter @Getter publicstatic classAddress{ private String country; private String province; private String city; } }

因為公司的要求，我們需要使用 Protobuff 完成序列化工作，並且需要生成API文件，所以我們一般需要補上Swagger註解和Tag註解。為了補上這兩種註解，你需要一點一點地敲鍵盤了。

稍微思考一下就會發現，補充Swagger註解的方法，一般是將相關POJO中同名欄位的JavaDoc復制過來，改為Swagger註解的格式即可，而補充Tag註解更簡單了，就是無腦的對欄位按順序進行編號，只要保證編號的順序是遞增的且不重復即可。

很明顯，上述工作是重復、單調、乏味、無聊、機械的，一切重復、單調、乏味、無聊、機械的工作都可以解放出來，下面直接給出解決方案，使用文字+圖片解釋太單薄了，直接給出動圖：

當然了，這個功能不止可以操作普通的POJO類，Controller類也是可以處理的：

簡單來說，我寫了一個IDEA外掛程式，在需要添加/刪除Swagger註解、Tag註解、JavaDoc註釋方面，能夠明顯提效，盡可能將大家從重復、單調、乏味、無聊的工作中解放出來。

快速開始

想要獲得這個外掛程式很簡單，開啟 Jetbrains Marketplace 的外掛程式頁面，直接下載、安裝即可：

https://plugins.jetbrains.com/plugin/22348-bitkylin-universal-generate

當然了，直接開啟 IntelliJ IDEA 進入 Settings -> Plugins -> Marketplace，搜尋 Bitkylin Universal Generate 也能夠找到。

安裝後，記得進入 Settings -> Tools -> Bitkylin Universal Generate ，將語言切換到中文（外掛程式考慮到了國際化，所以預設英文哦😉）。

外掛程式的基本用法，上面的動圖中略微展示了一下，不過動圖中只展示了兩個功能。開啟右鍵選單後可以看到，新增了好幾個功能哦，他們都是做什麽的呢？

核心功能

你可以透過右鍵選單，一鍵生成Swagger註解： @Api , @ApiOperation , @ApiModel , @ApiModelProperty ，一鍵生成Protostuff註解： @Tag 。

全域生成註解的最佳實踐，就是上面的動圖中演示的那樣，除了上面列出的全域一鍵生成註解外，還是有一些擴充套件功能，下面系統介紹一下外掛程式的核心功能。

對整個文件處理，統一生成註釋、註解

就像上面兩張動圖中演示的那樣，我們隨意開啟右鍵選單，可以看到選項說明中，作用範圍是整個文件，此時執行各個功能時，會對整個文件中的所有元素進行處理。

可以對指定欄位單獨生成註釋、註解

除了對整個文件統一處理外，你也可以對單個欄位進行處理，比如還是對上面列出的那個POJO類進行操作。首先將光標指向某個欄位名，開啟右鍵選單，此時外掛程式功能全都變更為了對當前欄位進行處理。依次進行如下操作：

刪除JavaDoc註釋

刪除剛剛生成的Swagger註解

填充JavaDoc註釋

填充Swagger註解

整個操作行雲流水~~~

當然我承認，手動刪除一個欄位的JavaDoc註釋、註解，比使用外掛程式刪除效率更高。。。但是如果要刪除整個類中所有的JavaDoc註釋、註解，還是使用外掛程式效率更高：

除了對POJO類中的欄位進行操作外，也可以將光標指向Controller類的方法、類名，指向POJO類的類名，選擇相應的功能即可對指定的元素進行處理。

將API層的POJO類轉換為Service層的POJO類

因為我們需要生成API文件，我們需要使用Protobuff完成序列化工作，所以我們一般需要在API層的POJO類上補充Swagger註解和Tag註解，但是Service層的POJO類不需要這些註解，最多只需要填充JavaDoc註釋即可。

考慮這樣一個場景：我們和二方對接時，拿到了一個二方API，為了對API進行隔離，我們可以將二方API中定義的Request、Response類復制一份在Service層自己用，可以考慮下面的操作：

將POJO類中的Swagger註解轉換為JavaDoc註釋

刪除POJO類中的所有Swagger、Tag註解

這些操作同樣是上面說的重復、單調、乏味、無聊、機械的工作，同樣可以使用外掛程式一鍵完成。上面演示了一大堆令人眼花繚亂的功能，我們開啟右鍵選單梳理一下，外掛程式提供的四個選項中，除了「註解轉JavaDoc」外，都演示過了。那麽很顯然，這個場景涉及到的就是「註解轉JavaDoc」這個功能。

我們使用「註解轉JavaDoc」功能，對整個文件一鍵處理，直接看動圖：

使用外掛程式可以一鍵優雅完成，如果手動做的話，那是真的浪費生命了！

功能釋義

上面演示了外掛程式的核心功能，如果僅僅看動圖的話，肯定會有很多疑惑的，這一小節盡可能的解釋各個功能及其原理。

刪除元素

這個功能有四個子選項，可以自由選擇要刪除的元素哦。一鍵刪除整個文件中的註釋、註解，其實還是很好用的。

外掛程式在展示選項前，會檢測當前計畫是否有swagger、protostuff依賴，如果沒有相關依賴，相關選項也是沒有的哦。

生成註解

上面演示的最多的就是這個功能，該功能會在Controller類相關元素上添加 @Api 、 @ApiOperation 註解，會在POJO類的相關元素上添加 @ApiModel 、 @ApiModelProperty 、 @Tag 註解。

目前標註 @Controller 、 @RestController 註解的類，或類名以Controller結尾的類，會被辨識為Controller類。標註 @Data 、 @Getter 、 @Setter 註解的類，會被辨識為POJO類。如果大家有更好的辨識Controller類和POJO類的方法可以留言😁。

值得一提的是， @Tag 註解中的序號，會根據欄位所處位置的不同，進行動態填充哦，原則是盡可能保證有序、唯一。

註解轉JavaDoc

核心用法是，上面重點介紹的「將API層的POJO類轉換為Service層的POJO類」場景，該功能做了以下事情：

將Swagger註解中的value欄位值提取出來，轉換為JavaDoc註釋

刪除POJO類中的所有Swagger、Tag註解

尋找JavaDoc

該功能用於給無任何註釋、註解的欄位，添加JavaDoc註釋。那麽問題來了，JavaDoc註釋是從哪來的呢？

首先不是由AI生成的，因為AI生成的文本不一定符合語意，並且較為緩慢，成本還高，需要聯網，因為有上述缺點所以廢棄了該方案。其次不是將欄位文本使用各種「轉譯」工具轉譯過來的，因為轉譯功能同樣有不符合語意，較為緩慢，成本高，需要聯網的缺點。然而外掛程式中該功能的特點是，語意盡可能精確、速度快、不用聯網，這是怎麽做到的呢？

首先則怎麽才能做到語意精確呢？自然是你曾經使用過這個欄位，並且標註過這個欄位的含義。你在使用IntelliJ IDEA開啟一個Project時，IDEA會對該Project中的各個單詞、檔名、檔型別等各種元素生成索引。

為什麽IDEA中的搜尋功能能夠快速找到指定的元素，就是這些索引的功勞，當然索引不只能IDEA自己用，我們開發的外掛程式也能用，具體可以參考Jetbrains的官方文件：

https://plugins.jetbrains.com/docs/intellij/file-based-indexes.html#implementing-a-file-based-index

當你對某個欄位使用「尋找JavaDoc」功能時，外掛程式會檢索到計畫中的所有同名欄位，透過精確或模糊匹配的方式，將所有相關的欄位全都檢索出來，然後把他們的JavaDoc註釋全都提取出來，去重、輸出就可以了。實際原理還是很簡單的，過程看起來繁瑣，但是執行效率極高哦，我監控過耗時，大機率不會超過1毫秒。