下载 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}；请将结果与网关变更一并提交。