OpenAPI 仕様をダウンロード

Minara ゲートウェイは、すべてのエンドポイントを OpenAPI 3.1 形式で完全かつ機械可読に記述しています。等価な 2 つのファイルは、このドキュメントサイトから静的アセットとして配信されます。

ダウンロード

• 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} に書き込みます。ゲートウェイの変更とともに結果をコミットしてください。