curiositech/windags-skills

Generador de Documentación de API

Extrae documentación de API a partir del código de manejadores de rutas existentes. Lee tu código fuente, infiere esquemas y produce especificaciones OpenAPI, tipos TypeScript y ejemplos curl ejecutables, basándose en la implementación real, no en la intención de diseño.

Disparadores de Activación

Actívalo en: "generar documentación de API", "OpenAPI desde código", "documentar endpoints", "referencia de API", "generación swagger", "documentación de endpoints", "crear tipos de API", "ejemplos curl para API"

NO para: Diseño de API desde cero --> api-architect | Creación de OpenAPI sin código fuente --> openapi-spec-writer | Pruebas de API --> test-automation-expert

Capacidades Principales

• Extraer definiciones de rutas de manejadores Express, Next.js App Router, Next.js Pages API Routes, Fastify y Hono
• Inferir esquemas de solicitud/respuesta a partir de tipos TypeScript, esquemas Zod o validación en tiempo de ejecución
• Generar especificaciones OpenAPI 3.0/3.1 con parámetros de ruta precisos, cadenas de consulta y cuerpos de solicitud
• Producir definiciones de tipos TypeScript que coincidan con el contrato real de la API
• Crear ejemplos curl para cada endpoint con datos de muestra realistas
• Documentar requisitos de autenticación rastreando cadenas de middleware
• Identificar la configuración de limitación de tasa y documentar los límites por endpoint
• Catalogar respuestas de error analizando patrones de lanzamiento/retorno en los manejadores
• Detectar endpoints no documentados (rutas que existen pero no tienen JSDoc o esquema)

Detección de Framework

Antes de generar cualquier cosa, identifica el framework. La estrategia de extracción difiere significativamente.

Express / Similar a Express

Señales: app.get(), router.post(), express.Router()
Fuente de ruta: app._router.stack o archivos de router explícitos
Cadena de middleware: el orden de app.use() importa para la detección de autenticación

Busca patrones de registro de rutas:

• router.get('/users/:id', authenticate, getUser) -- el middleware antes del manejador significa que se requiere autenticación
• app.use('/api/v1', rateLimiter({ max: 100 }), apiRouter) -- limitador de tasa aplicado a un subárbol

Next.js App Router

Señales: archivos route.ts que exportan GET, POST, PUT, DELETE, PATCH
Fuente de ruta: Convención del sistema de archivos en app/api/
Cadena de middleware: middleware.ts en los límites de directorio

Los parámetros de ruta provienen de nombres de carpeta: app/api/users/[id]/route.ts --> /api/users/{id}

Next.js Pages API Routes

Señales: pages/api/**/*.ts con export default handler
Fuente de ruta: Convención del sistema de archivos
Enrutamiento de métodos: switch req.method dentro del manejador

Fastify

Señales: fastify.get(), fastify.route(), propiedad schema en opciones de ruta
Fuente de ruta: Registro de plugins con fastify.register()
Esquema: Las rutas de Fastify a menudo ya tienen JSON Schema -- extráelo y conviértelo

Fastify es el framework más fácil de documentar porque las rutas frecuentemente declaran sus propios esquemas. Prioriza la extracción de schema.body, schema.response y schema.querystring existentes antes de inferir.

Hono

Señales: app.get(), app.post(), Hono(), zValidator()
Fuente de ruta: Encadenamiento de métodos en la instancia de Hono
Validación: basada en Zod a través del middleware zValidator

Hono con zValidator te proporciona esquemas Zod directamente. Convierte Zod --> JSON Schema --> esquema OpenAPI.

Proceso de Extracción

Paso 1: Descubrir Rutas

Escanea el proyecto en busca de registros de rutas. No te bases en un único punto de entrada: los frameworks a menudo dividen las rutas en varios archivos.

# Express: encontrar archivos de router
grep -rl "express.Router\|app.get\|app.post\|router\." src/ --include="*.ts" --include="*.js"

# Next.js App Router: encontrar manejadores de ruta
find src/app/api -name "route.ts" -o -name "route.js"

# Next.js Pages: encontrar rutas de API
find src/pages/api -name "*.ts" -o -name "*.js"

# Fastify: encontrar registros de rutas
grep -rl "fastify\.\(get\|post\|put\|delete\|route\)" src/ --include="*.ts"

# Hono: encontrar definiciones de rutas
grep -rl "app\.\(get\|post\|put\|delete\|patch\)" src/ --include="*.ts"

Paso 2: Extraer Esquemas

Para cada ruta, identifica las formas de solicitud y respuesta.

Orden de prioridad para fuentes de esquemas:

1. Esquemas de validación explícitos (Zod/Joi/Yup) (mayor confianza)
2. Anotaciones de tipos TypeScript en solicitud/respuesta
3. Declaraciones JSON Schema (Fastify)
4. Anotaciones JSDoc @param / @returns
5. Inferencia en tiempo de ejecución a partir de la construcción de la respuesta (menor confianza -- márcalo como aproximado)

Al usar inferencia en tiempo de ejecución (opción 5), marca siempre el esquema con x-inferred: true en la salida OpenAPI para que los consumidores sepan que puede estar incompleto.

Paso 3: Rastrear Autenticación

Recorre la cadena de middleware para cada ruta y determina los requisitos de autenticación:

• Sin middleware de autenticación: Marcar como security: [] (público)
• Middleware de token Bearer: Marcar como security: [{ bearerAuth: [] }]
• Middleware de clave API: Marcar como security: [{ apiKeyAuth: [] }]
• Autenticación por sesión/cookie: Marcar como security: [{ cookieAuth: [] }]
• Múltiples opciones de autenticación: Listar todas como alternativas en el array de seguridad

Paso 4: Catalogar Errores

Lee cada manejador y enumera cada respuesta de error:

• res.status(400).json(...) o throw new BadRequestError(...) --> esquema de respuesta 400
• res.status(401) --> 401 (incluir si hay middleware de autenticación presente incluso sin lanzamiento explícito)
• res.status(404) --> 404
• res.status(409) --> 409 (conflicto, común en operaciones de creación)
• res.status(422) --> 422 (fallo de validación)
• res.status(429) --> 429 (limitado por tasa, incluir si se detecta middleware limitador de tasa)
• res.status(500) --> 500 (siempre incluir como posibilidad)

Paso 5: Generar Salidas

Produce tres artefactos:

1. Especificación OpenAPI (YAML, no JSON -- más legible, más fácil de diferenciar)
2. Tipos TypeScript (archivo .d.ts independiente con todos los tipos de solicitud/respuesta)
3. Ejemplos curl (uno por endpoint, con encabezados y cargas útiles de muestra)

Puntos de Decisión

Cuando el código base NO tiene esquemas de validación

Si los manejadores aceptan req.body sin validación Zod/Joi, debes inferir los tipos a partir del uso. Busca:

• Patrones de acceso a propiedades: req.body.name, req.body.email --> { name: string, email: string }
• Desestructuración: const { name, email } = req.body --> misma inferencia
• Llamadas de inserción en base de datos: db.users.create({ name: body.name }) --> hacer referencia cruzada con el esquema de la BD si está disponible

Marca toda la especificación con una advertencia: x-schemas-inferred: true a nivel de información.

Cuando las rutas usan segmentos de ruta dinámicos

• Express: :id --> OpenAPI {id}
• Next.js: [id] --> OpenAPI {id}
• Next.js catch-all: [...slug] --> OpenAPI {slug} con nota sobre el comportamiento de array
• Fastify: :id --> OpenAPI {id}
• Hono: :id --> OpenAPI {id}

Cuando la forma de la respuesta varía según el código de estado

Documenta cada código de estado con su propio esquema. No combines 200 y 201 en un solo esquema si difieren. Patrón común:

responses:
  '200':
    description: Usuario encontrado
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
  '404':
    description: Usuario no encontrado
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'

Cuando los límites de tasa difieren por endpoint

Documenta los límites de tasa usando extensiones OpenAPI:

x-rate-limit:
  requests: 100
  window: 60s
  scope: por-clave-api

Si el limitador de tasa es global (aplicado una vez a nivel de aplicación), documéntalo en la sección info de nivel superior. Si es por ruta, documéntalo en cada operación.

Generación de Tipos TypeScript

Genera tipos que coincidan exactamente con la especificación OpenAPI. Usa tipos con marca para IDs cuando el código base los use.

// Generado a partir de la especificación OpenAPI -- no editar manualmente

export interface CreateUserRequest {
  name: string;
  email: string;
  role?: 'admin' | 'member' | 'viewer';
}

export interface CreateUserResponse {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'member' | 'viewer';
  createdAt: string; // ISO 8601
}

export interface ErrorResponse {
  error: {
    code: string;
    message: string;
    details?: Array<{
      field: string;
      issue: string;
    }>;
  };
}

export interface PaginatedResponse<T> {
  data: T[];
  meta: {
    page: number;
    perPage: number;
    total: number;
    hasMore: boolean;
  };
}

Generación de Ejemplos Curl

Genera un curl por endpoint. Usa datos realistas pero obviamente falsos.

# GET /api/users/:id -- Obtener un solo usuario
curl -X GET https://api.example.com/api/users/usr_abc123 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Accept: application/json"

# POST /api/users -- Crear un nuevo usuario
curl -X POST https://api.example.com/api/users \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "email": "[email protected]",
    "role": "member"
  }'

# GET /api/users -- Listar usuarios con paginación
curl -X GET "https://api.example.com/api/users?page=1&perPage=20&role=admin" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Accept: application/json"

Reglas para ejemplos curl:

• Incluir siempre la URL completa (usar https://api.example.com como base)
• Incluir todos los encabezados requeridos
• Usar -d con JSON formateado para cuerpos de solicitud
• Poner entre comillas las URLs que contengan parámetros de consulta
• Mostrar el método HTTP explícitamente incluso para GET
• Usar sk_test_... para tokens de autenticación (obviamente falsos)
• Usar valores de campo realistas, no "string" o "test"

Anti-Patrones

1. Documentar APIs Aspiracionales

Síntoma: La especificación describe endpoints que aún no existen en el código Solución: Solo documenta lo que el código realmente implementa. Si un endpoint planificado está en comentarios o en un archivo de especificación pero no en los manejadores, exclúyelo.

2. Ignorar Efectos Secundarios del Middleware

Síntoma: La documentación dice que el endpoint es público cuando en realidad requiere autenticación a través de un middleware padre Solución: Rastrea toda la cadena de middleware desde la raíz de la aplicación hasta el manejador. Un router.use(auth) arriba de la definición de la ruta significa que todas las rutas debajo requieren autenticación.

3. Asumir la Forma del Cuerpo de la Solicitud

Síntoma: Documentar req.body como any u object porque no hay validación Solución: Inferir a partir del uso (acceso a propiedades, desestructuración, llamadas a base de datos). Marcar como x-inferred: true. Recomendar agregar validación Zod.

4. Documentación de Errores Plana

Síntoma: Cada endpoint lista el mismo genérico "400 Bad Request" sin detalles Solución: Leer las rutas de error de cada manejador. Documentar los códigos de error y mensajes específicos devueltos. Diferentes fallos de validación deben mostrar diferentes respuestas de ejemplo.

5. Documentos Generados Obsoletos

Síntoma: La especificación se generó una vez y nunca se actualizó cuando el código cambió Solución: Generar en una ruta conocida (docs/openapi.yaml). Agregar una verificación de CI que regenere y compare con la especificación confirmada. Si divergen, fallar la compilación.

6. Documentación de Paginación Faltante

Síntoma: Endpoints de lista documentados sin esquemas de parámetros de consulta para paginación Solución: Si el manejador soporta page, limit, cursor, offset o parámetros similares, documéntalos con valores predeterminados y máximos.

7. Cargas de Archivos No Documentadas

Síntoma: Endpoints multipart/form-data documentados como JSON Solución: Detectar multer, formidable, busboy o el manejo nativo de archivos del framework. Usar el tipo de contenido multipart/form-data con el esquema binario adecuado.

Lista de Verificación de Calidad

[ ] Cada manejador de ruta en el código base tiene una operación OpenAPI correspondiente
[ ] Los parámetros de ruta coinciden entre el código y la especificación (sin discrepancias :id vs {userId})
[ ] Los esquemas del cuerpo de la solicitud cubren todos los campos requeridos y opcionales
[ ] Los esquemas de respuesta coinciden con la estructura JSON real (verificado leyendo el retorno del manejador)
[ ] Los requisitos de autenticación coinciden con el análisis de la cadena de middleware
[ ] La información de límite de tasa está documentada donde existe middleware de limitación de tasa
[ ] Las respuestas de error están catalogadas a partir de declaraciones reales de lanzamiento/retorno en los manejadores
[ ] Los ejemplos curl se ejecutan correctamente contra una instancia en ejecución
[ ] Los tipos TypeScript se compilan sin errores
[ ] No hay esquemas x-inferred sin documentar (cada uno marcado tiene un TODO para validación adecuada)
[ ] Los parámetros de paginación están documentados con valores predeterminados y máximos
[ ] Los endpoints de carga de archivos usan el tipo de contenido multipart/form-data
[ ] La especificación OpenAPI se valida con spectral o swagger-cli lint
[ ] La especificación generada se confirma en una ruta conocida para la comparación en CI

Artefactos de Salida

1. docs/openapi.yaml -- Especificación completa de OpenAPI 3.0/3.1
2. docs/api-types.d.ts -- Definiciones de tipos TypeScript para todas las formas de solicitud/respuesta
3. docs/api-examples.sh -- Ejemplos curl ejecutables para cada endpoint
4. docs/api-coverage.md -- Informe que enumera rutas documentadas vs no documentadas

Validación

# Lintear la especificación OpenAPI generada
npx @stoplight/spectral-cli lint docs/openapi.yaml

# Validar la estructura de la especificación
npx swagger-cli validate docs/openapi.yaml

# Generar un cliente TypeScript para verificar que los tipos compilan
npx openapi-typescript docs/openapi.yaml -o /tmp/api-check.d.ts
tsc --noEmit /tmp/api-check.d.ts

# Comparar con la última especificación confirmada (verificación CI)
diff <(cat docs/openapi.yaml) <(npx tsx scripts/generate-api-docs.ts --stdout) && echo "La especificación está actualizada" || echo "La especificación está obsoleta"

---

Cubre: Generación de OpenAPI | Extracción de tipos TypeScript | Creación de ejemplos curl | Documentación de autenticación | Documentación de límites de tasa | Catalogación de códigos de error

Úsalo con: api-architect (diseño primero, documentar después) | openapi-spec-writer (autoría manual) | test-automation-expert (pruebas de contrato contra la especificación generada)