生成接口文檔 IDEA 插件安裝方法

當有接口對接需求的時候，開發(fā)終于不用再擔心 API 文檔難寫了，也不用再一個個接口文檔重新寫！安裝這個 IDEA 插件，可以一步將文檔導入到 Postcat。

這款插件操作簡單，容易上手，能夠讓開發(fā)者省去API文檔編寫的工作，更專注于開發(fā)。插件通過分析用戶注釋進行接口解析，最終生成接口文檔并上傳至 Postcat 服務器，使得開發(fā)者可以在 Postcat 上進行 API 管理和分享，提高協(xié)作能力和開發(fā)速度。

和Swagger 有什么區(qū)別呢？

Postcat 插件不會入侵到代碼內(nèi)部，無需添加任何 jar 包依賴
插件通過分析用戶注釋進行接口解析，最終生成接口文檔并上傳至 Postcat 服務器，使得開發(fā)者可以在 Postcat 上進行 API 管理和分享，提高協(xié)作能力和開發(fā)速度。

Postcat 提供了多種拓展注釋，如@path、@url、@method、@name、@hidden和@required，這些注釋可以在設置界面進行自定義或兼容現(xiàn)有注釋。

此外，Postcat 還提供了注釋生成功能，對于沒有或僅有少量注釋的類和方法，開發(fā)者無需費力手動添加，該功能可以分析方法字段含義并自動生成注釋。開發(fā)者只需要檢查或根據(jù)實際場景進行微調(diào)，即可生成一份較完善的API文檔。

如果原有注釋不足，Postcat 會通過添加方式補充注釋，移除注釋時只會移除Postcat提供的那些拓展性注釋，不會破壞用戶自身的注釋。同時，開發(fā)者還可以使用"意圖"功能局部生成插件注釋，并進行調(diào)整和修改。

Postcat提供了多種 API 上傳方式，方便開發(fā)者在不同的場景下使用：

• 對于首次使用Postcat的現(xiàn)有項目，開發(fā)者可以使用主菜單中Tools分組下的Upload Project Api Doc來完成項目級別的接口上傳。
• 對于新需求下創(chuàng)建的Controller，在完成接口定義后，開發(fā)者可以右鍵菜單，選擇 Upload All Api 來進行單個文件級別全部上傳，做到先有文檔再有邏輯，前后端工作不再串行阻塞。
• 對于某個部分單獨接口的改動，無需全部上傳，開發(fā)者可以右鍵菜單，選擇Upload Api功能，該功能會展示當前編輯類的接口信息，并提供接口預覽和接口選擇界面，使得用戶可以勾選需要更新或上傳的目標API進行信息核對和上傳。

如何安裝配置？

IDEA 版本需大于 IntelliJ IDEA 2022.03

在 IDEA “設置-插件-Marketplace” 中搜索 Postcat，找到 Postcat 插件安裝即可。同時也可在IDEA插件市場上進行下載安裝，本地的IDEA沒有自動喚起時，可以直接把zip包拖入IDEA中即可完成安裝/更新。

• 填寫配置信息

• 首次上傳需要填寫配置信息，配置信息項目之間獨立。配置信息獲取途徑：登陸 Postcat 進入項目中獲取 Token、WorkspaceID 和 ProjectID。Server 默認填寫：https://postcat.com/api， 用戶無需修改
• Token獲取  

• WorkspaceID 和 ProjectID 獲取進入項目設置頁面，點擊項目名右側(cè)“問號”

1. 進入項目設置頁面，點擊項目名右側(cè)“問號”

• StringType 決定出入?yún)⒌淖址愋停挥袇?shù)名一開始就是遵守駝峰規(guī)范才會發(fā)現(xiàn)改變，預覽窗口可看到變化結(jié)果

1. 當參數(shù)名為userInfo，選擇 camelCase，依舊是userInfo，這是默認選項 

2. 當參數(shù)名為userInfo，選擇 lower_underscore，會變成user_info 

3. 當參數(shù)名為userInfo，選擇 UPPER_UNDERSCORE，會變成USER_INFO

• 注意事項

1. 進行解析上傳前，請確保 IDEA 在項目中已經(jīng)構(gòu)建完，相關依賴已經(jīng)下載好。
2. 強烈推薦使用插件定義的注釋，插件有強大的生成注釋功能，強烈建議先生成插件的注釋進行編輯再上傳，注釋可以在設置也進行自定義。
3. 在識別不到插件注釋時，僅對 Spring MVC、Swagger.v2和Swagger(OpenAPI).v3的注解只做部分簡單支持。為避免必要參數(shù)的缺失，推薦使用插件注釋。
4. 生成注釋功能會對Spring MVC、Swagger.v2 和Swagger(OpenAPI).v3的注解只做部分簡單支持，而不會讓你重頭編寫。
5. HTTP接口通過路由和請求方式判斷唯一做覆蓋更新處理
6. 對于已經(jīng)上傳的 API，在 web 上進行過手動修改，不建議再使用上傳功能，因為插件上傳會覆蓋掉之前的內(nèi)容。
7. 在生成/手敲了插件javadoc后，對接口uri，請求方式（GET/POST）等做了修改，需要手動修改插件javadoc，否則插件還是會識別到舊的插件javadoc信息。
8. 自動生成的類注釋默認會上傳到默認分組，請用戶自行填寫真實的分組，分組通過名字識別。如多級分組，則用.隔開，比如需要把接口傳到第三方分組下的用戶分組，則 group-name 填寫 第三方.用戶。
9. @group-name注釋 支持到方法級別，默認不生成，可手動添加到方法注釋，插件會幫你將當前方法存到對應分組中。
10. 項目級別的 api 掃描和上傳，頂部菜單[Tools -> Upload Project Api Doc]，具體使用規(guī)則看 項目級上傳。
11. 生成類注釋不在默認生成@required注釋，只會針對有javax.validation.constraints.NotNull注解的字段才生成。
12. 不推薦使用@remark注釋，插件保留了識別功能且將內(nèi)容拼接到字段說明中，生成類注釋不會自動生成。
13. 通過@PathVariable，POST方法默認把參數(shù)識別成 Formdata 類型，GET方法默認把參數(shù)識別成 query 類型。
14. //標識的注釋無法被識別出來，請使用/** */標識。