OpenAPI Frontend Sync

Overview

Duplicar tipos entre backend y frontend a mano es un trabajo tedioso y propenso al error que ya no hace falta. Si el backend expone un OpenAPI schema (FastAPI, NestJS con @nestjs/swagger, Django con drf-spectacular, etc.), un generador puede producir un cliente tipado para el frontend.

Principio: el backend es la única fuente de verdad del contrato. El cliente del frontend se genera desde el OpenAPI schema, nunca se escribe a mano.

Anunciar al inicio: "Aplicando openapi-frontend-sync antes de tocar el cliente de API en frontend."

Step 1: Confirmar que el backend expone OpenAPI

Verificar antes:

# FastAPI default
curl http://localhost:8000/openapi.json | jq '.info'

# NestJS con @nestjs/swagger
curl http://localhost:3000/api-json | jq '.info'

# Django + drf-spectacular
curl http://localhost:8000/api/schema/ | jq '.info'

# Spring Boot + springdoc
curl http://localhost:8080/v3/api-docs | jq '.info'

Si el endpoint responde con un JSON OpenAPI válido (versión 3.0+), sigue. Si no, esta skill no aplica — primero hay que activar OpenAPI en backend.

Step 2: Elegir y configurar el generador

Generadores comunes para frontend:

Setup mínimo en package.json:

{
  "scripts": {
    "generate:api": "openapi-ts -i http://localhost:8000/openapi.json -o src/lib/api/generated",
    "generate:api:clean": "rm -rf src/lib/api/generated && npm run generate:api"
  }
}

Reglas:

• Output a una carpeta clara (src/lib/api/generated/).
• Esa carpeta es read-only para humanos.
• Comando reproducible — no manual.

Step 3: Workflow de cambios — siempre backend primero

digraph workflow {
    "Cambio backend (schema, endpoint)" [shape=box];
    "Backend levantado en dev" [shape=box];
    "npm run generate:api en frontend" [shape=box];
    "Frontend: importar tipos del generated/" [shape=box];
    "Frontend: implementar consumo" [shape=box];

    "Cambio backend (schema, endpoint)" -> "Backend levantado en dev";
    "Backend levantado en dev" -> "npm run generate:api en frontend";
    "npm run generate:api en frontend" -> "Frontend: importar tipos del generated/";
    "Frontend: importar tipos del generated/" -> "Frontend: implementar consumo";
}

Razón: si haces el frontend primero, vas a inventar shapes que el backend no necesariamente produce. Backend primero garantiza que el tipo es real.

Step 4: Usar los tipos generados, no redeclarar

// ❌ Mal — tipo a mano que duplica el generado
type User = {
  id: string;
  email: string;
  nombre: string;
};

// ✅ Bien — importar el tipo generado
import type { User } from '@/lib/api/generated/types';
// O si el generador exporta por endpoint:
import type { GetUsersResponse } from '@/lib/api/generated';

Si el tipo generado tiene un nombre raro (a veces sale paths['/users']['get']['responses']['200']), crear un alias en un archivo específico:

// src/lib/api/types.ts
import type { components } from './generated/openapi';
export type User = components['schemas']['UserResponse'];
export type CreateUserDto = components['schemas']['UserCreate'];

Importar desde acá en lugar del archivo generado directo. Esto da un punto único de adaptación si el generador cambia.

Step 5: Nunca editar archivos en generated/

Los archivos generados se sobreescriben en cada npm run generate:api. Cualquier edición manual se pierde. Si necesitas:

• Wrapping: crear un archivo en src/lib/api/ (no en generated/) que importe y envuelva.
• Tipos derivados: crear un archivo de tipos que extienda los generados.
• Defaults: configurar el generador, no editar la salida.

Agregar a .gitignore solo si el generated se versiona implícitamente con CI. Si se commitea (más común), dejarlo trackeado pero con un comentario claro:

/* eslint-disable */
// AUTOGENERATED — DO NOT EDIT
// Run `npm run generate:api` to regenerate.

Step 6: Cross-repo (backend y frontend separados)

Si el backend vive en otro repo, hay tres patrones:

Documentar en CONTRIBUTING.md del frontend cómo conseguir el openapi.json actualizado.

Step 7: Verificar la sync con CI

Agregar al CI un job que:

1. Levante el backend.
2. Corra npm run generate:api.
3. Verifique que no hay diff vs el generated/ versionado:

git diff --exit-code src/lib/api/generated/

Si el diff es no-cero, el dev olvidó regenerar. Fallar el build. Esto previene la deriva silenciosa entre lo declarado en el código y lo real del backend.

Quick Reference

Common Mistakes

• Mantener tipos a mano que duplican el backend. Tarde o temprano divergen y el bug es silencioso.
• Editar archivos del generated/. Se pierden al regenerar.
• Implementar el frontend antes de regenerar después de un cambio backend. Inventas shapes que no existen.
• No tener comando reproducible (npm run generate:api). Cada dev regenera distinto y con flags distintos.
• Versionar el generated/ pero no validarlo en CI. Termina desactualizado y nadie se entera.

Red Flags

Nunca:

• Escribir tipos a mano que duplican el contrato del backend.
• Editar archivos dentro de la carpeta generated/.
• Implementar el consumo en frontend sin regenerar después de un cambio en backend.
• Asumir que el openapi.json está sincronizado sin verificar.

Siempre:

• Hacer el cambio en backend primero, regenerar, después tocar frontend.
• Importar tipos desde generated/ (directo o vía alias), no redeclarar.
• Tener npm run generate:api y npm run generate:api:clean como comandos reproducibles.
• Validar la sync con CI si los archivos generados se versionan.