資料夾

把型別與端點組織到巢狀路徑下，讓大型規格保持可瀏覽。資料夾是可選的：沒有任何資料夾欄位的規格會跟這個功能出現之前一樣平鋪顯示。一旦在任何一個型別或端點上設定資料夾，側欄就會自動切到樹狀檢視。

建立資料夾

點 Types 或 Endpoints 面板標題列上的 + 資料夾 圖示。清單中會出現一個內嵌輸入框；輸入路徑後按 Enter 確認。

auth/admin
users/internal
payments/v2/webhooks

• 分隔符號是 /，可以巢狀到任意深度。
• 每個段落允許的字元：字母、數字、_、.、- 與空白。不合法的輸入會被拒絕。
• 剛建立的資料夾是暫存狀態——它還沒有任何項目，因此不存在於規格中。把至少一個型別或端點拖進去，資料夾就會成為規格的一部分。如果在拖入任何項目前就重新整理，暫存資料夾會消失。

拖拉操作

兩個側欄都支援拖拉——這也是在資料夾之間移動項目的方式。抓一個型別列（或端點列）拖到資料夾標頭上就能把它搬過去；拖到清單頂端的空白區（或任何根層級的項目列）則會放回根。對該項目的 $ref 仍然能解析。鍵盤使用者可以用 Tab 把焦點移到該列，按 Space（或 Enter）抓取，用方向鍵在資料夾之間移動，按 Space 放下，或用 Escape 取消。

側欄的資料夾樹

一旦任何項目設定了資料夾：

• 沒有資料夾的項目會顯示在清單頂端（虛擬根），按字母排序。
• 有資料夾的項目會出現在下方可折疊的資料夾節點裡，每層一個節點。每個節點顯示箭頭、資料夾名，以及裡面的項目數（自己與子孫加總）。
• 點箭頭折疊或展開。折疊狀態會保存在 UI 偏好設定裡（不是規格內），重新整理也還在。

鍵為 auth/User 的型別和被歸到 auth 的端點，會在各自的面板裡並排出現在同一個 auth/ 資料夾下。

重新命名資料夾

把游標移到資料夾列上，點右側的 ⋯（更多） 按鈕，從選單裡選 重新命名資料夾。標題會變成可編輯的輸入框——輸入新名字後按 Enter（或點擊別的地方完成）。改名會一併改寫：

• 每個以該路徑開頭的型別鍵（auth/User → identity/User）。
• 每個指向被搬動型別的 RefType.ref（所以引用不會斷）。
• 每個以該路徑開頭的端點 folder 欄位。

就地改名只接受單一段落——輸入含 / 的多段路徑會被拒絕。如果要把資料夾搬到其他父資料夾底下，請把每個項目拖到新的父資料夾上。

當資料夾空了，節點會自動消失：把最後一個項目搬走，資料夾就不見了。

直接在資料夾裡新增項目

每個資料夾列的操作群組（游標移上去才會出現）由左到右有三個按鈕：

• + Add endpoint（在型別建構器是 + Add type）— 直接在這個資料夾裡建立一個新項目。
• + folder — 預先把新資料夾輸入框填入 {parent}/，方便你建立巢狀子資料夾。輸入葉節點名稱（例如在 auth/ 後面接 oauth），按 Enter — auth/oauth 就會出現在暫存資料夾。
• ⋯（更多） — 既有的選單（匯出資料夾 / 重新命名資料夾 / 刪除資料夾）。

暫存資料夾的列上也有 + Add 按鈕（點下去會同時放入第一個項目，並把暫存資料夾轉成正式資料夾）。暫存資料夾還沒有 + folder 按鈕——等它變成正式資料夾後，三個按鈕的完整操作群組才會出現。

刪除資料夾

更多選單裡的 刪除資料夾 是連帶刪除：資料夾內的每個端點或型別都會一起被刪掉。執行前會跳出確認視窗顯示數量（「刪除資料夾「auth」與其中的 5 個端點？」）。

型別資料夾還多了一道防呆機制：如果資料夾內的型別有被你規格的「其他地方」引用，刪除動作會被中止，並用 toast 列出哪些地方還在用它。先把這些引用清掉（或把型別搬出資料夾），再來重試。

不同資料夾下的同名項目

資料夾會對短名字做命名空間，所以 auth/User 和 admin/User 可以同時存在，是兩個不同的型別。跨資料夾的引用要用完整路徑：

RefType { ref: "auth/User" }

沒有 / 的引用指向根資料夾的型別（ref: "User" 代表根層級那個鍵為 User 的型別，不是 auth/User）。

OpenAPI 來回保真

資料夾透過一個輕量的 vendor extension 在 export / import 之間保留：

• 匯出時每個型別鍵會被攤平：auth/User 變成 components.schemas.auth_User，旁邊帶一個 x-folder: "auth"。有 folder 的端點會在 operation 上附帶 x-folder。
• 匯入時，任何帶 x-folder 的 schema 會被還原到對應的資料夾路徑鍵；它的 $ref 也會跟著改寫。沒有 x-folder 的 schema 會落在根。

外來的 OpenAPI 檔案（沒有 x-folder）會以平鋪型別匯入——匯入後你可以用 + 資料夾 加上拖拉整理。

資料夾不做的事

• 不取代 tags。 端點仍然可以有 OpenAPI tags[]；資料夾跟 tags 是正交的。如果沒有任何端點設定 folder，側欄仍然用 tags 分組（維持原本行為）。
• 不支援資料夾內手動排序。 資料夾內的項目依短名字母排序；沒有每個項目的位置欄位。
• 沒有空資料夾。 一個資料夾只在至少有一個子孫時存在。
• 不跨規格。 資料夾是單一規格內部的組織工具。