Swagger API Docs — Guía de Uso

Versión: v1.0.46 Última actualización: 19-03-2026 URL Local: http://localhost:8000/api/docs URL Producción: https://crearack.com/api/docs

1. Qué es Swagger

Swagger (ahora OpenAPI) es una interfaz web interactiva que documenta automáticamente todos los endpoints de la API de CreaRack Pro. Django Ninja genera esta documentación a partir del código — cada vez que añades un endpoint, aparece automáticamente en Swagger sin escribir documentación manual.

Tecnología

2. Acceso

Restricción de acceso: Swagger y el spec OpenAPI están restringidos a superusers en producción. Usuarios normales y visitantes anónimos reciben un 404. Esto se controla via AdminPathsMiddleware (core/middleware/admin_paths.py).

Cómo acceder

1. Abre CreaRack Pro en el navegador y haz login con una cuenta superuser
2. Navega a /api/docs
3. Verás todos los endpoints agrupados por categoría

Nota: Si no eres superuser, /api/docs devuelve 404 como si no existiera.

3. Interfaz — Qué ves

3.1 Header

En la parte superior se muestra:

• Título: “CreaRack Pro API”
• Versión: 1.0.0
• Descripción: “SaaS-ready API for Data Center Management”

3.2 Tags (Categorías)

Los endpoints están agrupados por tags. Click en un tag para expandir/colapsar:

3.3 Endpoint Card

Cada endpoint muestra:

[POST]  /api/signage/signage/playlists    Create playlist

• Método HTTP (GET/POST/PATCH/DELETE) con color distintivo
• URL completa
• Resumen (el summary del decorador)

4. Probar Endpoints (“Try it out”)

4.1 Pasos

1. Click en un endpoint para expandirlo
2. Verás:
   • Parameters: Query params, path params
   • Request Body: Schema JSON esperado (si es POST/PATCH)
   • Responses: Códigos posibles (200, 400, 404) con schemas
3. Click “Try it out”
4. Rellena los parámetros o modifica el JSON del body
5. Click “Execute”
6. Verás:
   • Curl command: El comando equivalente en terminal
   • Request URL: La URL final construida
   • Response body: La respuesta real del servidor
   • Response code: El código HTTP
   • Response headers: Headers de la respuesta

4.2 Ejemplo: Crear una Playlist

1. Expande POST /api/signage/signage/playlists
2. Click “Try it out”
3. En el body, escribe:

{
  "name": "Lobby Morning",
  "description": "Contenido para el lobby por la mañana",
  "items": [
    {"asset_id": 1, "duration_seconds": 10, "transition": "fade", "order": 1},
    {"asset_id": 2, "duration_seconds": 15, "transition": "none", "order": 2}
  ],
  "loop": true
}

4. Click “Execute”
5. Recibirás la playlist creada con su id, total_duration, etc.

4.3 Ejemplo: Listar Media con Filtros

1. Expande GET /api/signage/signage/media
2. Click “Try it out”
3. Rellena el campo asset_type con video
4. Click “Execute”
5. Verás solo los assets de tipo vídeo

4.4 Ejemplo: Upload de Archivo

1. Expande POST /api/signage/signage/media/upload
2. Click “Try it out”
3. En el campo file, click “Choose File” y selecciona una imagen
4. Rellena name y asset_type
5. Click “Execute”
6. El archivo se sube y se procesa automáticamente

5. Schemas (Modelos de Datos)

5.1 Dónde verlos

Al final de la página de Swagger, sección “Schemas”, están todos los modelos:

• PlaylistCreateIn — campos para crear playlist
• PlaylistOut — respuesta al obtener playlist
• MediaAssetOut — respuesta con detalles de media
• DeploymentCreateIn — campos para crear deployment
• etc.

5.2 Cómo se generan

Cada clase Schema en signage/api/schemas.py aparece automáticamente:

class PlaylistCreateIn(Schema):
    name: str                    # Campo obligatorio
    description: str = ''       # Opcional, default vacío
    items: list = []            # Opcional, default lista vacía
    loop: bool = True           # Opcional, default True

Swagger muestra esto como:

• name — required, type: string
• description — optional, type: string, default: ""
• items — optional, type: array, default: []
• loop — optional, type: boolean, default: true

6. Códigos de Respuesta

7. Uso Avanzado

7.1 Descargar el Spec OpenAPI

El spec JSON completo está disponible en:

Puedes usar este archivo para:

• Generar clientes SDK automáticos (Python, JS, Go, etc.)
• Importar en Postman o Insomnia
• Generar documentación estática con ReDoc o Slate

7.2 Importar en Postman

1. Abre Postman
2. Click “Import”
3. Pega la URL: https://crearack.com/api/openapi.json
4. Postman creará automáticamente una Collection con todos los endpoints

7.3 CSRF Token

Las llamadas desde Swagger funcionan porque usa la cookie de sesión. Si quieres hacer llamadas desde curl o scripts externos:

# Primero obtén el CSRF token
curl -c cookies.txt https://crearack.com/accounts/login/

# Luego úsalo en las llamadas
curl -b cookies.txt -H "X-CSRFToken: <token>" \
     https://crearack.com/api/signage/signage/playlists

7.4 Filtrar Endpoints

Swagger UI tiene una barra de búsqueda en la parte superior. Escribe para filtrar:

• signage — solo endpoints de Digital Signage
• playlist — solo endpoints de playlists
• POST — solo métodos POST

8. Seguridad en Producción

Nota: Swagger en producción solo es accesible para superusers. Usuarios normales y visitantes anónimos reciben 404, como si la ruta no existiera. Esto evita exponer el mapa completo de la API a usuarios del SaaS.

9. Troubleshooting

10. Referencia de URLs

Mantenido por: Claude (Anthropic) + Equipo CreaRack

Véase también

• [[decision—20260101—django-ninja-vs-drf]] — ADR Django Ninja vs DRF
• [[crearack-tech—backend—network-tools]] — herramientas de red backend
• [[crearack-tech—backend—network-observatory]] — backend del Network Observatory
• [[crearack-tech—agents—dev-core]] — perfil de subagente dev-core
• [[crearack-tech—guides—testing]] — guía de testing
• [[crearack-tech—guides—testing-local-guide]] — testing en entorno local