Swagger UI es el estándar de oro para documentación de APIs REST. Pero si has intentado documentar una base de datos Firestore con él, probablemente te hayas topado con un muro. Firestore no es una API REST — es una base de datos de documentos con colecciones, subcolecciones y datos anidados. Necesita un tipo diferente de herramienta.
¿Qué es Swagger UI?
Swagger UI renderiza documentación interactiva a partir de especificaciones OpenAPI. Está diseñado para APIs REST: endpoints, métodos HTTP, cuerpos de request/response, códigos de estado. Si estás construyendo una API REST, Swagger es excelente — muestra a los desarrolladores exactamente cómo llamar cada endpoint, qué parámetros enviar y qué respuestas esperar.
Por Qué Swagger No Encaja con Firestore
Firestore es fundamentalmente diferente de una API REST:
Sin endpoints
Firestore usa referencias de colección, no rutas URL. No hay GET /users ni POST /orders — interactúas a través del SDK de Firebase con rutas de colección como users/{userId}/orders.
Colecciones ≠ rutas
Una colección de Firestore es un grupo de documentos con esquemas flexibles, no un recurso REST con formas fijas de request/response. Las subcolecciones agregan otra dimensión que REST no modela bien.
El esquema difiere de los contratos de API
OpenAPI describe interfaces HTTP. Firestore necesita esquema a nivel de documento: tipos de campo, reglas de validación, objetos anidados y las relaciones entre colecciones y subcolecciones.
¿Qué es FireSchema?
FireSchema está diseñado específicamente para bases de datos de documentos. En lugar de especificaciones OpenAPI, usa archivos JSON Schema — uno por colección — organizados en carpetas que reflejan tu jerarquía de Firestore. Renderiza un visor interactivo que muestra el árbol de colecciones, campos de documentos, tipos y descripciones. JSON Schema.
Comparación de Características
| Característica | Swagger UI | FireSchema |
|---|---|---|
| Diseñado para | APIs REST | Bases de datos NoSQL |
| Formato de especificación | OpenAPI (YAML/JSON) | JSON Schema |
| Modelo de datos | Endpoints y métodos | Colecciones y documentos |
| Subcolecciones | No soportado | Carpeta = jerarquía |
| Backend requerido | Frecuentemente sí | Nunca |
| Tiempo de configuración | Minutos a horas | Menos de 5 minutos |
| Pruebas en vivo | Sí (llamadas API) | No (documentación de solo lectura) |
Cuándo Usar Cada Uno
Usa Swagger UI cuando:
- -Tienes una API REST con endpoints HTTP
- -Necesitas pruebas interactivas de API (try-it-out)
- -Tu equipo ya usa especificaciones OpenAPI
Usa FireSchema cuando:
- -Usas Firestore o cualquier base de datos de documentos
- -Quieres documentar tu modelo de datos (no endpoints de API)
- -Necesitas documentación sin backend que funcione como archivos estáticos
- -Quieres empezar en menos de 5 minutos
Usa ambos cuando:
Tu proyecto tiene una API REST respaldada por Firestore. Usa Swagger para la capa de API y FireSchema para la capa de base de datos.
Comienza Ahora
FireSchema le da a tu base de datos Firestore la misma calidad de documentación que Swagger le da a las APIs REST. Configúralo en 5 minutos y despliégalo como un sitio estático. Get started in 5 minutes →