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

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

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

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

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

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

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

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

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

如何安裝配置？

IDEA 版本需大于 IntelliJ IDEA 2022.03

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

• 填寫配置信息

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

• WorkspaceID 和 ProjectID 獲取進(jìn)入項(xiàng)目設(shè)置頁(yè)面，點(diǎn)擊項(xiàng)目名右側(cè)“問號(hào)”

1. 進(jìn)入項(xiàng)目設(shè)置頁(yè)面，點(diǎn)擊項(xiàng)目名右側(cè)“問號(hào)”

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

1. 當(dāng)參數(shù)名為userInfo，選擇 camelCase，依舊是userInfo，這是默認(rèn)選項(xiàng) 

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

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

• 注意事項(xiàng)

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