Swagger UI は REST API ドキュメントのゴールドスタンダードです。しかし、Firestore データベースを Swagger でドキュメント化しようとしたことがあるなら、壁にぶつかったことでしょう。Firestore は REST API ではなく、コレクション、サブコレクション、ネストされたデータを持つドキュメントデータベースです。異なる種類のツールが必要です。
Swagger UI とは？
Swagger UI は OpenAPI 仕様からインタラクティブなドキュメントを生成します。REST API 向けに設計されています：エンドポイント、HTTP メソッド、リクエスト/レスポンスボディ、ステータスコード。REST API を構築しているなら、Swagger は優れたツールです — 各エンドポイントの呼び出し方、送信すべきパラメータ、期待されるレスポンスを開発者に正確に示します。
Swagger が Firestore に適さない理由
Firestore は REST API とは根本的に異なります：
エンドポイントがない
Firestore は URL ルートではなくコレクション参照を使用します。GET /users や POST /orders はありません — Firebase SDK を通じて users/{userId}/orders のようなコレクションパスで操作します。
コレクション ≠ ルート
Firestore コレクションは、固定されたリクエスト/レスポンス形式を持つ REST リソースではなく、柔軟なスキーマを持つドキュメントのグループです。サブコレクションは REST ではうまくモデル化できない別の次元を追加します。
スキーマは API コントラクトとは異なる
OpenAPI は HTTP インターフェースを記述します。Firestore にはドキュメントレベルのスキーマが必要です：フィールドの型、バリデーションルール、ネストされたオブジェクト、コレクションとサブコレクション間の関係。
FireSchema とは？
FireSchema はドキュメントデータベース向けに設計されています。OpenAPI 仕様の代わりに、JSON Schema ファイル — コレクションごとに1つ — を使用し、Firestore の階層を反映したフォルダに整理します。コレクションツリー、ドキュメントフィールド、型、説明を表示するインタラクティブなビューアを生成します。 JSON Schema.
機能比較
| 機能 | Swagger UI | FireSchema |
|---|---|---|
| 対象 | REST API | NoSQL データベース |
| 仕様フォーマット | OpenAPI (YAML/JSON) | JSON Schema |
| データモデル | エンドポイントとメソッド | コレクションとドキュメント |
| サブコレクション | 非対応 | フォルダ = 階層 |
| バックエンドの要否 | 多くの場合必要 | 不要 |
| セットアップ時間 | 数分〜数時間 | 5分以内 |
| 試行呼び出し | あり（API 呼び出し） | なし（読み取り専用ドキュメント） |
それぞれの使い分け
Swagger UI を使う場合：
- -HTTP エンドポイントを持つ REST API がある場合
- -インタラクティブな API テスト（試行機能）が必要な場合
- -チームが既に OpenAPI 仕様を使用している場合
FireSchema を使う場合：
- -Firestore またはドキュメントデータベースを使用している場合
- -API エンドポイントではなくデータモデルをドキュメント化したい場合
- -静的ファイルで動作するバックエンド不要のドキュメントが必要な場合
- -5分以内に始めたい場合
両方を使う場合：
プロジェクトが Firestore をバックエンドとする REST API を持っている場合。API レイヤーには Swagger を、データベースレイヤーには FireSchema を使用してください。
始めましょう
FireSchema は、Swagger が REST API に提供するのと同じ品質のドキュメントを Firestore データベースに提供します。5分でセットアップし、静的サイトとしてデプロイしましょう。 Get started in 5 minutes →