OpenAPI Renderer

OpenAPI Renderer（id openapi-renderer，目前版本 1.0.0）把筆記資料夾裡的 OpenAPI 文件畫成 API 文件：tag 與 operation 導覽、參數與欄位樹、範例與 cURL。需要 NoteCraftApp 1.6.0 以上。

它是讀文件的地方，不會替你送出請求。站台是純靜態的，範例區只提供可複製的 cURL 與 fetch。

支援的版本

不支援的：

• YAML：資料檔只吃 JSON，先轉檔
• 外部 $ref（不是 #/ 開頭的）：不解析，型別欄位顯示 ref 原字串
• 試打 API：不提供

安裝與映射

npx notecraftapp install-plugin openapi-renderer --apply "**/*.openapi.json"

不帶 --apply 的話，自己在 .notecraft/plugins.json 加一條：

{
  "plugins": [
    { "plugin": "openapi-renderer", "files": ["**/*.openapi.json"] }
  ]
}

慣例是檔名以 .openapi.json 結尾。網址照一般資料檔的規則只去掉 .json：

安裝流程見安裝來源，規則寫法見映射規則 plugins.json。

資料檔

資料檔就是 OpenAPI 文件本身，不用改寫格式。build 時只檢查外形：

• 要有 openapi（3. 開頭）或 swagger 其中之一
• 要有 info，裡面要有 title 與 version

不合這兩條 build 會失敗。其他瑕疵，例如 $ref 斷掉、operationId 重複，不會讓 build 失敗：無法解析的部分略過，重複的 operationId 改用 method/path 當連結，view 模式下在瀏覽器 console 列出警告。

{
  "openapi": "3.1.0",
  "info": {
    "title": "訂單 API",
    "version": "1.0.0",
    "description": "訂單系統對外的 REST API。"
  },
  "x-notecraft-back-to": "/notes/orders/overview",
  "servers": [{ "url": "https://api.example.com/v1" }],
  "tags": [{ "name": "orders", "description": "建立與查詢訂單" }],
  "paths": {
    "/orders/{id}": {
      "get": {
        "tags": ["orders"],
        "operationId": "getOrder",
        "summary": "取得單筆訂單",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "成功" },
          "404": { "description": "找不到訂單" }
        }
      }
    }
  }
}

外形檢查用的 schema 見 repo 裡的 schema.json。example/ 底下有三份範例：Swagger Petstore（3.2.0）、含循環 $ref 與 oneOf 等邊界案例的 orders（3.1），以及只有兩支端點、沒有 tag 的 health。

標題、描述與回到筆記

OpenAPI 文件沒有 meta 欄位，所以這個 plugin 在自己的 manifest 裡改指頁面資訊的來源：

• 標題用在頁首、瀏覽器分頁標題、頁籤與指令面板
• info.description 可以用 Markdown。頁首只取第一段的純文字，站內搜尋收全文；各個 operation 的內容不進搜尋索引
• x-notecraft-back-to 只接受 / 開頭的站內路徑，例如 "/notes/orders/overview"。不符合時忽略並在 build 時警告，不會失敗

頁面上能做什麼

1234

1method 篩選（可複選）2回到來源筆記3Operations：tag → operation4各 tag 的大小與 method 分布

1. 1method 篩選（可複選）
2. 2回到來源筆記
3. 3Operations：tag → operation
4. 4各 tag 的大小與 method 分布

導覽

左側依序是篩選、總覽、Operations（tag → operation）與 Schemas。

• 篩選框比對 path、summary 與 operationId，/ 可以直接聚焦
• method 按鈕可以複選，只列出選中的 method
• 篩選狀態不寫進網址，重新整理就清掉
• 外殼寬度在窄螢幕時，導覽改成覆蓋式、預設收合

operation 不超過 4 支、也都沒有 tag 的小型文件，不顯示導覽，總覽直接列出所有 operation 與 schema。

四種頁面

沒寫 tags 的 operation 歸在一個統一的分組裡。標了 deprecated 的 operation 與參數會加上「已棄用」。

Operation 頁的操作

• path 裡的 {參數} 可以點，會捲到參數表的那一列
• Request Body 與 Responses 並列欄位樹與範例（版面窄時上下排）；有多種 content type 時可以切換，有多個範例時可以從下拉選單挑，沒有範例時由 schema 產生
• Responses 依狀態碼切換
• 「複製 path」「複製連結」；Schema 頁另有「複製 schema JSON」

範例請求

每支 operation 下方有範例請求，可以在 cURL 與 fetch 之間切換。選了哪一種會記在瀏覽器，所有 OpenAPI 頁共用；頁面剛載入時一律先顯示 cURL。文件列了多個 servers 時，可以從下拉選單換伺服器。範例裡的 <…> 是佔位，要換成實際值。

鍵盤操作見快捷鍵的「OpenAPI Renderer」。

連結到特定位置

/view/ 頁的位置會同步到網址 hash，可以直接分享或寫進筆記連結：

/view/api/orders.openapi#tag/orders
/view/api/orders.openapi#op/getOrder
/view/api/orders.openapi#op/getOrder/responses/404
/view/api/orders.openapi#schema/Order

沒有 operationId 的 operation 用 #op/<method>/<path>。完整的格式見網址參數的「OpenAPI 頁」。

嵌進筆記

import PluginView from "@/components/PluginView.astro";

{/* 單一 operation 的卡片 */}
<PluginView src="api/orders.openapi.json" options={{ operation: "getOrder" }} anchor="op/getOrder" />

{/* 不指定 operation：整份 API 的總覽縮影 */}
<PluginView src="api/orders.openapi.json" />

• operation 卡片：method 與 path、summary、operationId、驗證、參數、Request Body 與主要回應的第一層欄位，以及其他回應的狀態碼
• 總覽縮影：API 標題、數量、method 分布與 tag 清單，點 tag 開到文件頁的該 tag。tag 超過 8 個時只列最大的 6 個
• options.operation 填 operationId，沒有 operationId 的寫 method/path，例如 get/orders/{id}。對不到時卡片裡顯示錯誤，build 不會失敗
• anchor 不會從 options.operation 自動推導，想讓「開啟完整檢視頁」直接跳到那一支，要自己寫上

選項

寫在 plugins.json 規則的 options，或 <PluginView> 的 options：

型別不對的值改用預設，view 模式下在 console 警告。