下載 OpenAPI 規範

Minara 網關以 OpenAPI 3.1 格式提供每個端點的完整機器可讀描述。兩個等價文件均作為靜態資源由本站點提供。

下載

• openapi.yaml：可讀且慣用的 YAML。
• openapi.json：相同規範的 JSON 編碼。

規範中的版本字段與 Minara 的 package.json 版本保持一致，因此倉庫中的副本可在不同版本間進行比較。

覆蓋範圍

apps/agent/src/gateway/api.ts 中註冊的每條路由在規範中都有對應條目，包括流式聊天（/v1/chat/stream）、投資組合和永續功能、個性化重建器與記憶 CRUD、工作流管理以及 OAuth 流程。CLAUDE.md §8a 將運行中網關與此文件之間的偏差視為 P1 問題；tests/unit/gateway/route-coverage.test.ts 中的覆蓋測試會阻止未提供相應 RouteSpec 條目的新端點發布。

使用方式

Swagger UI：打開 https://editor.swagger.io，選擇 File → Import URL，粘貼已部署的 /openapi.yaml URL。

Postman：選擇 Import → Link，粘貼相同 URL。Postman 會識別 servers[].url 並預填主機；Bearer 認證通過 bearer 安全方案配置。

openapi-typescript：生成完整類型的客戶端代碼：

npx openapi-typescript https://your-host/openapi.yaml -o src/api-types.ts

curl 冒煙測試：如果網關啟用了認證，請使用 Authorization: Bearer <GATEWAY_AUTH_TOKEN>：

curl -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
     http://localhost:8080/v1/profile | jq

本地重新生成

規範會在構建時從驅動本站點各路由參考頁的同一 ROUTES 數組生成。修改 apps/agent/src/gateway/api.ts 後，可通過以下命令重建：

npm --prefix docs run generate:openapi
# (or: npm --prefix docs run generate — runs both api + openapi)

生成器會寫入 docs/public/openapi.{yaml,json}；請將結果與網關變更一併提交。