Categories
程式開發

寫文檔太麻煩,試試這款IDEA 插件吧!


前言每次開發完新項目或者新接口功能等,第一件事就是提供接口文檔。說到接口文檔,當然是用Markdown 了。各種複制粘貼字段,必填非必填,字段備註,請求返回示例等等。簡直是浪費時間哇。所以想到了開發一款插件來解決重複複製文檔的問題。下面來看我介紹介紹這款插件。 PS:插件比較簡陋,還需要不斷迭代。公眾號:liuzhihangs,記錄工作學習中的技術、開發及源碼筆記;時不時分享一些生活中的見聞感悟。歡迎大佬來指導!

為什麼開發插件

每次在對外提供接口時都要寫文檔,各種麻煩,並且文檔耗費了很大一部分時間。也使用了一些文檔工具,在線寫作工具,最終還是比較喜歡自己手寫文檔。

使用過的生成工具

Swagger : 添加依賴,配置類及描述信息,然後在方法及實體上添加註解,啟動項目便可以通過訪問xxxx/swagger-ui.html 查看接口文檔;API Doc :添加配置文件及註釋,安裝npm 並通過執行命令生成文檔;SmartDoc :添加依賴及註釋後執行測試類生成文檔;API2DOC :添加依賴,開啟註解,通過註解配置生成文檔。

上面四種方法,無疑都需要添加依賴,使用註解等方式,可以說有一定的代碼侵入性。

使用過的接口文檔工具

ShowDoc :曾經一段時間很喜歡用這個, Markdown 語法,方便直觀。不過就是要自己手寫;YApi :現在在使用YApi,可以通過Swagger 導入;VS Code 寫Markdown :直接離線寫Markdown ,可以導出PDF、Word、Html。

自己寫文檔比較重複,繁瑣,不過個人比較喜歡Markdown 格式。簡潔直觀。並且配合著我之前寫的IDEA 插件copy-as-json 和Tookit 將實體複製為json 字符串,用來快速生成請求樣例和返回樣例,還是可以減少一定的工作量的。

其他使用方式

使用各種在線協作工具,騰訊文檔、語雀、石墨文檔。使用離線版本PDF、Word、Excel 等等。也有一些其他的文檔工具,不過自己都沒有使用過或者調研過了。

基本上這些文檔工具要么通過代碼侵入的方式生成文檔,要么自己手擼文檔。總體來說各有千秋。

個人手寫更方便

個人比較喜歡的就是手寫Markdown 。

下面是兩幅圖:

寫文檔太麻煩,試試這款IDEA 插件吧! 1

寫文檔太麻煩,試試這款IDEA 插件吧! 2

有時候文檔比較多的時候,就寫的累了。尤其是最近使用了YApi , 個人感覺使用Swagger 然後導入到YApi 裡面還是挺方便的,省時省力。

後來就想,既然YApi 提供接口,那我是不是可以自己生成,然後傳到YApi 中呢?

所以就開始著手這個插件的開發。

使用及功能

既然已經開發好最基礎版本了,當然也得介紹下,首先看圖:

寫文檔太麻煩,試試這款IDEA 插件吧! 3

通過圖簡單介紹下使用以及功能:

使用

使用方式很簡單,直接在Controller 類或者Controller 類的公共非靜態方法內右鍵喚出菜單,單機Doc View 即可。

寫文檔太麻煩,試試這款IDEA 插件吧! 4

只能在Controller 類或者Controller 類的公共非靜態方法內使用。至於兩者的區別,後續會介紹。

這裡可能會有小伙伴們發出疑問:Dubbo 接口也要寫文檔,難道不可以麼?

嗯~ 可以!但是現在不支持~

功能

基本功能就是截圖展示的那樣。

左側顯示接口名及列表,右側展示接口信息;點擊Copy 按鈕就會將展示的信息原本對應的Markdown 文本複製到剪貼板;在Class 內部點擊,生成的如圖所示的列表,而在方法內右鍵生成的是只有本方法的。

使用說明

Dubbo 接口,當前版本不支持,所以下面介紹的全都是在Class 上的使用:

要生成文檔,需要滿足什麼條件?

目標類內部有方法;類必須有相關Spring 註解。

1. org.springframework.stereotype.Controller

2. org.springframework.web.bind.annotation.RestController

生成文檔,接口方法需要滿足什麼條件?

文檔的方法:Public 修飾且非靜態方法(static 修飾),方法上包含以下註解:

org.springframework.web.bind.annotation.PostMappingorg.springframework.web.bind.annotation.GetMappingorg.springframework.web.bind.annotation。 PatchMappingorg.springframework.web.bind.annotation.RequestMapping

文檔模版是否可以設置?

當前版本文檔模版只有展示的這個,不支持自定義模版。

接口名稱是如何設置的?

接口名稱默認取值如圖截圖所示類名#方法名;

寫文檔太麻煩,試試這款IDEA 插件吧! 5

支持在註釋上使用@name 設置接口名。

寫文檔太麻煩,試試這款IDEA 插件吧! 6

接口描述是從哪裡獲取的?

接口描述直接取的方法註釋;如果有@description 標籤,則會優先使用標籤對應的描述。

寫文檔太麻煩,試試這款IDEA 插件吧! 7

請求路徑是如何生成的?

取Class 和Method 上的path 進行拼裝組成。

請求方式如何設置?

根據Method 上的註解生成。

請求參數及請求示例的需要設置什麼?

根據是否有@RequestBody 註解,生成請求Header 是否為json 還是form。同時會檢測請求參數中是否有@RequestHeader 註解;

寫文檔太麻煩,試試這款IDEA 插件吧! 8

對像生成列表;根據請求是json 還是form 生成對應的請求示例。

返回參數及返回示例怎么生成?

支持對象,返回空,返回帶泛型方式。這裡的泛型僅支持單個泛型且名稱為T。

寫文檔太麻煩,試試這款IDEA 插件吧! 9

總結

問答環節

**Q: Doc View 插件去哪裡下載? **

A:

可以直接通過IDEA 插件倉庫,直接搜索名稱即可;在GitHub 通過Releases 下載;關注公眾號並發送Doc View 相關關鍵字(doc/doc view)獲取。

**Q: Doc View 是否開源? **

A: 是的。開源地址為:https://github.com/liuzhihang/doc-view“,有興趣的小伙伴,可以給個Star ,如果想增加一些功能,也可以提PR。

結束語

插件開發從最開始開發到今天發布第一版,中間經歷了很長一段時間,畢竟只是業餘時間開發,就斷斷續續的寫,不過現在最簡單版本已經可以使用了。

目前來看,只有一個Copy 功能,不過基本上可以滿足使用。至於其他的需求,比如:自定義模版、支持Dubbo 接口、預覽導出等功能就需要後續不斷迭代了。

個人開發精力有限,小伙伴在使用過程中遇到肯定會遇到bug,或者是有其他的功能及使用建議,都可以通過以下方式反饋:

關注公眾號:『 劉志航』 通過讀者討論進行留言;在GitHub 上提Issues;在插件幫助頁面留言;文章結尾留言;

最後,感謝小伙伴們的支持。歡迎下載體驗,並提出相關建議及意見。