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

Postcat發表於2023-03-28
當有介面對接需求的時候,開發終於不用再擔心 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

相關文章