OpenAPI 仕様
実行中サーバが直接提供するライブ仕様です。
Hono サーバはルートが使うのと同じ Zod スキーマから生成した OpenAPI 3.1 仕様を直接提供します。同期しなければならない別の仕様ファイルは ありません。仕様、SDK 型、ルートハンドラはすべて同じ 1 つのソースから 派生します。
どこで見つけるか
サーバが実行中のとき:
| URL | 形式 |
|---|---|
http://localhost:3099/openapi.json | 生の JSON (機械可読) |
http://localhost:3099/docs | Swagger UI (インタラクティブ) |
http://localhost:3099/spec | プレーンテキストダンプ |
3099 は startSnaServer({ port }) が返したポートに置き換えてください。
認証契約
ランタイム仕様は components.securitySchemes.bearerAuth を含み、document
level に security: [{ bearerAuth: [] }] を設定します。GET /health だけが
公開 operation で、security: [] として示されます。保護された operation
には標準 error envelope を使う共通の 401 と 403 response が含まれます。
/openapi.json、/docs、/spec に直接アクセスする場合も、他のランタイム
ルートと同じ認証 middleware を通ります。静的ドキュメント生成では docs build
script 内だけで unsafeDisableAuth を使うため、live secret なしで published
reference を生成できます。
ユースケース
- 他言語クライアントを生成。
/openapi.jsonに任意の OpenAPI codegen を接続できます。スキーマが strict (Zod 派生) なので、出力は型安全です。 - インタラクティブ探索. Swagger UI で認証や body エディタを使い、 ブラウザからすべてのルートを呼び出せます。
- CI で契約を固定。 仕様をディスクにスナップショットし、ビルドごと に diff を確認します。意図しない公開表面の変更が diff として現れます。
安定性
ルートは SNA ワークスペース全体で semver に従います。後方非互換のルート 変更はメジャーバージョンとしてリリースされます。OpenAPI タグがルートを 表面別 (Sessions、Agent、Permissions、Chat) にまとめるため、生成 クライアントも自然なグループを持ちます。
ルートと一行説明の完全リストは HTTP ルート にあります。 各ルートが emit できるイベントタイプは イベント を 確認してください。