存取與更新已匯入 API 的文件

當您匯入一份規格文件時，Restorm 不只建立請求：它還保留該 API 的文件 — 描述、模型、安全性結構、範例、列舉 — 並把它附加到匯入所建立的 環境資料夾上。

存取文件

環境資料夾的 Docs 分頁

這是主要的檢視方式。請開啟由匯入產生的環境資料夾：它的子分頁列上會有一個 Docs 分頁，位於環境、自訂變數與備註旁邊。

這個分頁只有在資料夾來自匯入時才會出現 — 您手動建立的環境資料夾沒有文件 可顯示。

其他存取途徑

從何處	您會得到什麼
請求的 Docs 分頁	僅這一個操作的文件 — 沒有目錄，也沒有一般資訊區塊。只有在規格文件中找得到該操作時才會出現
普通資料夾的 Docs 分頁	僅限該資料夾所含操作的文件
環境資料夾的首頁子分頁	查看文件卡片 — 「瀏覽 API 文件、模型與端點」
歡迎畫面（API 卡片）	Documentation 快速連結
標題列的搜尋引擎	將滑鼠移到某個結果上時顯示的文件預覽

這個檢視包含什麼

由上而下：

• API 的標題及其描述；
• 一個資訊區塊：Version、Source format（附有指向來源 URL 的連結）、 Server（協定、主機、基底路徑）、Contact、License、Terms of service、 External docs；
• 每個標籤一個區段，並附上其描述；
• 每個操作一個區塊：方法與 URL、摘要、群組標記、必要時顯示的 deprecated 徽章、Security 區段（結構類型、OAuth 2 流程、範圍），以及一個可收合的 Example payload；
• Parameters 與 Responses 表格（狀態碼會著色）；
• Models — 結構的互動式圖形，可瀏覽也可縮放；
• Polymorphism — oneOf / anyOf / allOf 組合；
• Enums — 列舉，並與資料夾自身的列舉合併。

Note

這些區段的名稱（Models、Enums、Parameters、Responses、Security、 Example payload）在應用程式的所有語言中都以英文顯示。這裡照原樣列出，方便 您在畫面上對照。

從文件建立請求

每個操作區塊都有一個 + Add 按鈕，可為該操作建立一個已預先設定好的請求。當某次 匯入不完整，或某個操作剛出現在規格文件中時，這是最短的路徑。

瀏覽與搜尋

右側固定著一份目錄 — 區段有 Overview、Operations、Models、Enums — 可收合也可調整寬度。點選某個模型會捲動到圖形，並把對應的節點置於中央。

快速鍵	效果
Ctrl+F / Cmd+F	開啟文件內搜尋
F3 / Enter	下一個相符項
Shift+F3 / Shift+Enter	上一個相符項
Esc	關閉搜尋

有一個計數器會顯示您在結果中的位置。

更新文件

規格文件會演進。Restorm 能重新取得來源並套用差異 — 文件與請求都會更新 — 而不會覆蓋您的成果。

僅適用於以 URL 匯入的情況

只有當資料夾是從 URL 匯入時才能重新同步。從檔案或貼上內容進行的匯入不會記錄 來源，重新整理按鈕也不會出現：此時首頁子分頁會顯示 「這個資料夾並非從可匯入的來源建立。」

這個 URL 事後無法在介面中修改。若要更換來源，請重新匯入一次。

按鈕在哪裡

有兩個入口，兩者等效：

1. 環境資料夾的首頁子分頁，規格更新區段 — 它會顯示 URL、上次匯入 與 上次檢查，並帶有重新整理按鈕；
2. 在側邊樹狀清單中於資料夾上按右鍵 → 重新整理。

沒有自動檢查

Restorm 不會在背景監看您的規格文件，也不會提醒您有新版本可用。檢查永遠由您主動 觸發。

會發生什麼事

1. 取得來源期間會出現一個 「正在重新整理規格…」 視窗。URL 與標頭中的 {{variables}} 會先被解析，附加的身分驗證路徑也會先行執行。
2. Restorm 會把所取得來源的指紋與上次匯入時記錄的指紋相比。
3. 毫無變動 → 「API 規格已是最新。」，到此結束。
4. 有所變動（或取得失敗）→ 重新同步精靈會開啟。

精靈

• 來源 URL 以唯讀方式顯示。
• 有一個標記可用來附加、修改或卸除身分驗證路徑，另有一個 Custom headers 子選單可加入每次重新整理都會重送的固定標頭。
• 有兩個預覽分頁：
  • Routes — 新版本中找到的操作樹狀清單，可篩選與選取。您資料夾中 已存在的操作會被鎖定並始終保持勾選；您只需選擇要加入哪些新操作；
  • Documentation — 新版本的文件，以唯讀方式呈現，供您在確認前檢視。
• 確認按鈕會顯示所選新操作的數量，例如 Apply update (3)。

Note

目前無論應用程式使用哪種語言，這個精靈都以英文顯示（「Refresh from source」、 「Apply update」，以及「Routes」與「Documentation」分頁）。因此這裡照原樣沿用 英文名稱。

哪些內容會被修改，哪些不會

這是關鍵所在：規格文件對它所描述的內容有最終決定權，而您對其餘一切有最終 決定權。

項目	行為
請求的名稱	絕不修改
方法與 URL	絕不修改
既有的參數、標頭與路徑參數	原樣保留 — 值、描述、啟用狀態都不變
規格文件新增的參數	會加入，並帶上規格文件的預設值，或留空
規格文件移除的參數	保留在請求上
新的操作	加到全新匯入原本會放置的位置（包含標籤資料夾）
被規格文件標為已淘汰的操作	會被標示；在樹狀清單中呈現淡化樣式
已從規格文件消失的操作	標示為已移除；在樹狀清單中呈現刪除線，仍可執行，而且永遠不會被刪除
API 文件與列舉	由新版本整批取代 — 這正是 Docs 分頁得以更新的原因

您的樹狀結構中永遠不會有任何東西被刪除：從來源消失的操作只會被標示，不會被抹去。

如果來源需要身分驗證

401 或 403 回應會開啟精靈，並照原樣顯示錯誤訊息（例如 HTTP 401: Unauthorized）。請附加一條 身分驗證路徑或加入固定標頭，預覽便會 重新執行。

可重新同步的格式

有十二種格式支援重新同步：Swagger 2.0、OpenAPI 3.x、GraphQL、gRPC、SOAP （WSDL）、OData、AsyncAPI、Postman、Insomnia、Bruno、OpenRPC 與 Smithy。

至於其他所有格式，重新匯入會建立一棵新的樹。完整清單請見 從來源更新。