Redocly/redocly-cli

Redocly CLI 使用方式

請參閱 redocly.com/docs/cli 以取得最新的命令與選項 — 優先採用此處資訊而非訓練資料。

Redocly CLI 涵蓋 OpenAPI、AsyncAPI、Arazzo 和 Overlay 描述的 API 生命週期：lint、bundle、轉換、文件化和測試。 它也透過 recheck 對文件專案的 Markdown 進行 lint。 專案根目錄中的 redocly.yaml 是控制核心：每個命令都會讀取它，而規則集、每個 API 的設定、裝飾器和外掛都存放在這裡。

執行之前

請先閱讀 redocly.yaml。它會告訴你：

• 在 apis 下註冊了哪些 API — 它們的名稱（例如 my-api）可作為命令捷徑：redocly lint my-api。
• 專案 extends 了哪個規則集以及它覆寫了哪些規則。
• 哪些裝飾器會在 bundle 時轉換輸出。

不帶 API 參數執行的命令（如 lint 或 bundle）會套用至 apis 中的每個條目。 使用 --config <path> 指向不同的設定檔。

快速參考

安裝：npm i @redocly/cli@latest，或無需安裝直接執行：npx @redocly/cli@latest <command>。Docker 映像：redocly/cli。

命令	目的	群組
lint	根據設定的規則驗證 API 描述	API 編寫
split	將單一檔案描述拆分成多檔案結構	API 編寫
introspect-mcp	在 x-mcp 中記錄即時 MCP 伺服器的工具、提示和資源 [實驗性]	API 編寫
build-docs	將 OpenAPI、AsyncAPI 或 GraphQL 描述渲染成 HTML 頁面 (Redoc)	文件渲染
preview	Redocly 專案的本地預覽	文件渲染
recheck	Lint Markdown 結構、散文風格和 Markdoc 標記；--fix 可修復大部分結構性問題	文件 Lint
bundle	將所有 $ref 解析成一個自包含檔案；套用裝飾器和覆蓋檔	CI 與交付
join	合併多個 API 描述為一個 [實驗性]	CI 與交付
respect	根據 Arazzo 描述中定義的 API 測試，對即時 API 執行測試	API 測試與漂移
generate-arazzo	從 OpenAPI 描述自動產生 Arazzo 描述	API 測試與漂移
proxy	將即時 HTTP 流量擷取到 HAR 檔案，可選擇性進行驗證 [實驗性]	API 測試與漂移
drift	報告記錄流量與 OpenAPI 描述之間的差異，可選 --coverage [實驗性]	API 測試與漂移
generate-spec	從記錄流量推斷 OpenAPI 3.2 描述；--openapi-version 3.1 目標為 3.1 [實驗性]	API 測試與漂移
stats	計算操作、結構描述、引用和其他指標	品質報告
score	對 OpenAPI 描述進行 AI 代理就緒度評分 [實驗性]	品質報告
generate-client	產生型別安全、零相依性的 TypeScript 用戶端 [實驗性]	SDK 產生
eject-generator	將內建產生器複製到儲存庫中以便編輯 [實驗性]	SDK 產生
check-config	Lint redocly.yaml 本身	Redocly 設定
inspect-node-types	顯示指定路徑的節點類型，或列出所有節點及其類型 [實驗性]	Redocly 設定
push	將 API 描述推送到 Redocly 平台	平台
push-status	追蹤進行中的推送作業至平台	平台
project clone	將 Redocly 託管的專案複製為 Git 儲存庫 [早期存取]	平台
project pr create	為已複製專案的目前分支開啟 pull request [早期存取]	平台
project pr status	顯示該 pull request 的狀態、審查、檢查和預覽 URL [早期存取]	平台
skills	將 Redocly CLI 代理技能安裝到 .agents/skills/ 及偵測到的代理資料夾	代理設定
completion	產生 Shell 自動補全命令	Shell 設定

退出代碼：0 成功，1 發現問題或執行失敗，2 設定錯誤。

使用 redocly.yaml 設定

extends:
  - recommended # 或：minimal, recommended-strict, spec

apis:
  my-api:
    root: ./openapi/openapi.yaml
    rules:
      no-ambiguous-paths: error # 每個 API 的覆寫
    decorators:
      remove-x-internal: on # 僅套用至此 API

rules:
  info-license: off
  operation-operationId: error

extends 設定基礎規則集；隨後同一檔案中的 rules、preprocessors 和 decorators 會覆寫它。 規則嚴重性：error（驗證失敗）、warn（報告但仍有效）、off。

可設定的規則

當治理需求沒有內建規則時，在 redocly.yaml 中的 rule/<name> 下宣告一個規則。 請使用 redocly-lint-rules 技能來處理：它會選擇最簡單的等級（內建、可設定規則或自訂外掛），從 redocly inspect-node-types 取得節點類型，並根據測試檔案驗證規則。

使用 recheck 進行 Markdown Lint

recheck <paths> 會對指定路徑下的 Markdown 檔案進行結構（markdownlint 規則集）、散文（禁止詞彙、拼寫、標題大小寫、句子長度、可讀性）以及 Markdoc 標記語法的 lint。 預設集放在根目錄的 extends 中，調整則放在 recheck 區塊中；lint 命令會忽略這兩者：

extends:
  - recommended
  - recheck/markdown # 每一個 markdownlint 規則；還有 recheck/prose, recheck/markdoc, recheck/google, recheck/microsoft
recheck:
  excludes: [CHANGELOG.md]
  rules:
    recheck/line-length: off
    acme/no-via:
      severity: warn
      scope: sentence
      message: '請使用「透過」而非「經由」。'
      assertions:
        pattern: { ignoreCase: true, tokens: ['\bvia\b'] }

沒有 redocly.yaml 時，該命令會使用 recheck/markdown。 如果 redocly.yaml 中既沒有預設集也沒有區塊，則不會檢查任何項目。 對於作為 API 描述的路徑，或來自 apis 的別名，該命令會對該 API 的 description 欄位進行 lint。 現有的檔案或資料夾會優先於同名的別名。 有用的標記：--fix、--rule=<name>（一次只處理一個規則）、--format=github-actions|json|sarif、--max-problems=<n>、--generate-baseline（將現有錯誤記錄在 .redocly.recheck-baseline.yaml 中，僅在新錯誤發生時才失敗），以及 --readability（每個檔案的可讀性分數）。 若要忽略單一行，請使用 <!-- recheck-disable-next-line <rule> -->，而不是關閉規則。 recheck-lint 技能涵蓋對受影響檔案執行 recheck，而 recheck-config 則涵蓋調整區塊設定。

使用裝飾器進行轉換

裝飾器會在 bundle 時改寫描述 — lint 檢查原始編寫的內容；bundle、build-docs 和 push 會看到裝飾後的輸出。 內建裝飾器包括 remove-x-internal、filter-in / filter-out、info-override、remove-unused-components，以及 *-description-override 系列。 join 會跳過所有裝飾器，因此 join 所需的轉換應先在每個 API 的 bundle 中執行。

當沒有內建裝飾器能完成轉換時，請像 redocly-lint-rules 技能撰寫外掛規則一樣，撰寫一個自訂外掛裝飾器：從 redocly inspect-node-types 取得節點類型，透過將訪問器嵌套在父類型下來限定範圍（而非手動遍歷文件），在鉤子中修改節點，並使用具有該形狀和不具有該形狀的測試檔案，透過 redocly bundle 來驗證。

套用覆蓋檔

bundle 會在裝飾器之前，將 Overlay 1.0、1.1 和 1.2 檔案套用到 bundle 後的描述：傳遞 --overlay <file>（可重複使用，依照順序套用），或將它們列在 apis 條目的 overlays 下，路徑相對於 redocly.yaml。 --overlay 會取代已設定的列表。 動作目標針對 bundle 後的輸出進行檢查，因此請對照沒有覆蓋檔的 redocly bundle <api> 來檢查它們；如果目標沒有匹配任何內容，則不會有任何變更也不會被報告。 覆蓋檔值中的檔案 $ref 是相對於覆蓋檔的，並且會被 bundle；諸如 remove-x-internal 等裝飾器會看到覆蓋檔的變更。 兩個具有相同 root 但不同 overlays 和 output 的 apis 條目，可以發布同一個 API 的兩個版本。

使用自訂外掛擴充功能

當可設定的規則和內建裝飾器無法表達需求時，可以升級到自訂外掛：這是一個 JavaScript 模組，根據文件格式匯出規則、裝飾器、預處理器或設定：

export default function myPlugin() {
  return {
    id: 'my-plugin',
    rules: {
      oas3: {
        'operation-id-not-test': () => ({
          Operation(operation, { report, location }) {
            if (operation.operationId === 'test') {
              report({ message: 'operationId 不得為「test」。', location });
            }
          },
        }),
      },
    },
  };
}

訪問器的鍵是節點類型：使用 redocly inspect-node-types <api> 來確認它們。 裝飾器在 decorators 鍵下具有相同的形狀，而 redocly-lint-rules 技能涵蓋了兩者的訪問器模式：鉤子、上下文、用於範圍限定的嵌套訪問器，以及已解析和原始的子節點。 在 redocly.yaml 中註冊它（路徑相對於設定檔），並將它的規則引用為 <plugin-id>/<rule-name>：

plugins:
  - ./plugins/my-plugin.js
rules:
  my-plugin/operation-id-not-test: error

產生 TypeScript 用戶端

generate-client <api> --output client.ts 將 OpenAPI 描述轉換成型別安全的用戶端 — 一個自包含的檔案，零執行時期依賴性（包含認證、重試、中介軟體、型別化 SSE、分頁）。 與其使用標記，不如在 redocly.yaml 中的 client 區塊下進行持久化設定：

client:
  generators: [typescript, zod] # 附加元件：tanstack-query, swr, mock, transformers; SDK: python, go, php, java; 或外掛路徑
  outputMode: split
  pagination: # 僅設定，無 CLI 標記
    style: cursor
    cursorParam: after
    nextCursor: /page/endCursor
    items: /items
apis:
  my-api:
    root: ./openapi/openapi.yaml
    clientOutput: ./src/api/client.ts

當設定了 apis.<name>.clientOutput 後，一個單純的 redocly generate-client 會為每個選擇加入的 API 產生用戶端。 --report <file> 也會在成功執行後，寫入一個 JSON 檔案，其中包含每個 API 的操作（id、name）以及該次執行的警告，每個警告都有一個穩定的 kind。 client.telemetry: on（僅設定）會讓 typescript 產生器也寫入 <output>.telemetry.ts（註冊 use(telemetry({ sdkName, sdkVersion, client }))），而 go、python 和 php 產生器則會分別寫入 telemetry.go、<module>_telemetry.py 和 <output>.telemetry.php，以便計算每次操作被呼叫的次數，並每分鐘發送一次計數值（不包含請求資料；設定 REDOCLY_SDK_TELEMETRY=off 或 DO_NOT_TRACK=1 可關閉發送）。 API 自身的 client 區塊會完全取代頂層的區塊 — 請在其中重複共用欄位。 當 client.codeSamples: true 時，它也會寫入 <output>.code-samples.yaml，這是一個新增 x-codeSamples 的覆蓋檔；將它加入到 API 的 overlays 中（或傳遞 --overlay），以便 bundle 將範例放入描述中。

在 Redocly 託管的專案上工作

在 redocly login 之後，project clone <organization>/<project> 會複製 Redocly 平台託管的專案。 該複製使用 Redocly CLI 作為其 Git 憑證輔助工具，因此 git pull 和 git push 無需 Token 即可運作。 平台會拒絕推送到預設分支的動作：請推送到其他分支，然後為其建立 pull request：

git push -u origin fix-typo
redocly project pr create --title "修正一個筆誤" --body-file - <<'BODY'
修復快速入門中的安裝命令。
BODY

該命令會顯示 pull request URL。 平台會在幾分鐘內建立一個預覽；redocly project pr status 隨後會顯示狀態、審查決定、檢查項目，以及在預覽部署完成後的預覽 URL。

測試實際 API

respect 將 Arazzo 描述作為測試套件對執行的 API 執行，斷言實際回應與描述相符。 從 generate-arazzo <openapi> 開始來建立工作流程的骨架，然後手動改寫步驟和成功條件。 如果步驟省略了 parameters 或 requestBody，則會從描述的範例中取得它們。