Swagger UI 是 REST API 文档的黄金标准。但如果您尝试用它来记录 Firestore 数据库,可能已经遇到了问题。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 集合是一组具有灵活 Schema 的文档,而不是具有固定请求/响应格式的 REST 资源。子集合增加了 REST 无法很好建模的另一个维度。
Schema 不同于 API 契约
OpenAPI 描述的是 HTTP 接口。Firestore 需要文档级别的 Schema：字段类型、验证规则、嵌套对象以及集合与子集合之间的关系。
什么是 FireSchema？
FireSchema 专为文档数据库而构建。它使用 JSON Schema 文件（而非 OpenAPI 规范）— 每个集合一个文件 — 按照镜像 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。使用 Swagger 记录 API 层,使用 FireSchema 记录数据库层。
开始使用
FireSchema 为您的 Firestore 数据库提供与 Swagger 为 REST API 提供的同等质量的文档。5 分钟内完成设置,并作为静态站点部署。 Get started in 5 minutes →