IDEA 外掛上新！ 生成介面文件就是這麼快！

Postcat發表於2023-03-28
Idea
當有介面對接需求的時候，開發終於不用再擔心 API 文件難寫了，也不用再一個個介面文件重新寫！安裝這個 IDEA 外掛，可以一步將文件匯入到 Postcat。

這款外掛操作簡單，容易上手，能夠讓開發者省去API文件編寫的工作，更專注於開發。外掛透過分析使用者註釋進行介面解析，最終生成介面文件並上傳至 Postcat 伺服器，使得開發者可以在 Postcat 上進行 API 管理和分享，提高協作能力和開發速度。

和Swagger 有什麼區別呢？

Postcat 外掛不會入侵到程式碼內部，無需新增任何jar包依賴

外掛透過分析使用者註釋進行介面解析，最終生成介面文件並上傳至 Postcat 伺服器，使得開發者可以在 Postcat 上進行 API 管理和分享，提高協作能力和開發速度。

Postcat 提供了多種擴充註釋，如@path、@url、@method、@name、@hidden和@required，這些註釋可以在設定介面進行自定義或相容現有註釋。

此外，Postcat 還提供了註釋生成功能，對於沒有或僅有少量註釋的類和方法，開發者無需費力手動新增，該功能可以分析方法欄位含義並自動生成註釋。開發者只需要檢查或根據實際場景進行微調，即可生成一份較完善的API文件。

如果原有註釋不足，Postcat 會透過新增方式補充註釋，移除註釋時只會移除Postcat提供的那些擴充性註釋，不會破壞使用者自身的註釋。同時，開發者還可以使用"意圖"功能區域性生成外掛註釋，並進行調整和修改。

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

  • 對於首次使用Postcat的現有專案，開發者可以使用主選單中Tools分組下的Upload Project Api Doc來完成專案級別的介面上傳。
  • 對於新需求下建立的Controller，在完成介面定義後，開發者可以右鍵選單，選擇 Upload All Api 來進行單個檔案級別全部上傳，做到先有文件再有邏輯，前後端工作不再序列阻塞。
  • 對於某個部分單獨介面的改動，無需全部上傳，開發者可以右鍵選單，選擇Upload Api功能，該功能會展示當前編輯類的介面資訊，並提供介面預覽和介面選擇介面，使得使用者可以勾選需要更新或上傳的目標API進行資訊核對和上傳。

如何安裝配置？

IDEA 版本需大於 IntelliJ IDEA 2022.03
在 IDEA “設定-外掛-Marketplace” 中搜尋 Postcat，找到 Postcat 外掛安裝即可。同時也可在IDEA外掛市場上進行下載安裝，本地的IDEA沒有自動喚起時，可以直接把zip包拖入IDEA中即可完成安裝/更新。

1. 填寫配置資訊

首次上傳需要填寫配置資訊，配置資訊專案之間獨立。
配置資訊獲取途徑：登陸 Postcat 進入專案中獲取 Token、WorkspaceID 和 ProjectID。

  1. Server 預設填寫：https://postcat.com/api， 使用者無需修改
  2. Token獲取

  3. WorkspaceID 和 ProjectID 獲取

    1. 進入專案設定頁面，點選專案名右側“問號”

  1. StringType 決定出入參的字串型別，只有引數名一開始就是遵守駝峰規範才會發現改變，預覽視窗可看到變化結果

    1. 當引數名為userInfo，選擇 camelCase，依舊是userInfo，這是預設選項
    2. 當引數名為userInfo，選擇 lower_underscore，會變成user_info

    3. 當引數名為userInfo，選擇 UPPER_UNDERSCORE，會變成USER_INFO

      2. 注意事項

  2. 進行解析上傳前，請確保 IDEA 在專案中已經構建完，相關依賴已經下載好。
  3. 強烈推薦使用外掛定義的註釋，外掛有強大的生成註釋功能，強烈建議先生成外掛的註釋進行編輯再上傳，註釋可以在設定也進行自定義。
  4. 在識別不到外掛註釋時，僅對Spring MVC、Swagger.v2和Swagger(OpenAPI).v3的註解只做部分簡單支援。為避免必要引數的缺失，推薦使用外掛註釋。
  5. 生成註釋功能會對Spring MVC、Swagger.v2 和Swagger(OpenAPI).v3的註解只做部分簡單支援，而不會讓你重頭編寫。
  6. HTTP介面透過路由和請求方式判斷唯一做覆蓋更新處理
  7. 對於已經上傳的 API，在 web 上進行過手動修改，不建議再使用上傳功能，因為外掛上傳會覆蓋掉之前的內容。
  8. 在生成/手敲了外掛javadoc後，對介面uri，請求方式（GET/POST）等做了修改，需要手動修改外掛javadoc，否則外掛還是會識別到舊的外掛javadoc資訊。

  9. 自動生成的類註釋預設會上傳到預設分組，請使用者自行填寫真實的分組，分組透過名字識別。

    1. 如多級分組，則用.隔開，比如需要把介面傳到第三方分組下的使用者分組，則 group-name 填寫 第三方.使用者。
  10. @group-name註釋 支援到方法級別，預設不生成，可手動新增到方法註釋，外掛會幫你將當前方法存到對應分組中。
  11. 專案級別的 api 掃描和上傳，頂部選單[Tools -> Upload Project Api Doc]，具體使用規則看 專案級上傳。
  12. 生成類註釋不在預設生成@required註釋，只會針對有javax.validation.constraints.NotNull註解的欄位才生成。
  13. 不推薦使用@remark註釋，外掛保留了識別功能且將內容拼接到欄位說明中，生成類註釋不會自動生成。
  14. 透過@PathVariable，POST方法預設把引數識別成 Formdata 型別，GET方法預設把引數識別成 query 型別。
  15. //標識的註釋無法被識別出來，請使用/* /標識。

瞭解 Postcat：

Postcat 是一個強大的開源、跨平臺（Windows、Mac、Linux、Browsers...）的 API 開發測試工具，支援 REST、Websocket 等協議（即將支援 GraphQL、gRPC、TCP、UDP），幫助你加速完成 API 開發和測試工作。

Postcat 核心功能：

  • API 文件管理：視覺化 API 設計，生成 API 文件
  • API 測試：自動生成測試引數，自動生成測試用例，視覺化資料編輯
  • 外掛擴充：眾多外掛擴充套件產品功能，打造屬於你和團隊的 API 開發平臺
  • Mock：根據文件自動生成 Mock,或建立自定義 Mock 滿足複雜場景
  • 團隊協作：既能實現 API 分享也能可以建立雲空間共同協作

Postcat 優勢：

  • 免登入即可測試：省去繁瑣的驗證登入的操作
  • 介面簡潔：沒有冗餘的功能與複雜選項
  • 免費：中小團隊以及個人使用
  • 豐富的外掛：支援資料遷移、主題、API 安全等高達 25 款外掛
  • 國產：能更好的理解國內使用者的需求，與開發團隊溝通無障礙
  • 完善的使用者文件：跟著操作就能快速上手

多提 Issue !多反饋！

在使用過程中有任何疑問，可以進群交流，也可以線上提 Issue（強烈推薦這種開源的方式），提問題本身就已經在貢獻社群了：
https://github.com/Postcatlab/postcat/issues

如果喜歡，不妨 Star 支援一下

這個專案是開源的，如果你覺得這個專案還不錯的話，不妨點個 Star 支援一下！

Github ：
https://github.com/Postcatlab/postcat

相關文章