/api-docs

name: api-docs
description: "Usar para documentar API con endpoints, parámetros y ejemplos. Activar ante: documentar API, endpoints, OpenAPI, Swagger, parametros, respuestas de la API"

Documentar API

Resumen

Este skill genera documentación completa de una API, cubriendo cada endpoint con sus parámetros, respuestas, códigos de error y ejemplos de uso. La documentación de API es el contrato entre el backend y sus consumidores (frontend, servicios externos, desarrolladores de terceros); si está mal documentada, genera confusión, bugs y soporte innecesario.

El formato puede ser Markdown para documentación legible o OpenAPI (Swagger) para documentación interactiva y generación automática de clientes.

Proceso

1. **Identificar los endpoints a documentar.** Revisar el código del proyecto para listar todas las rutas expuestas. Agruparlas por recurso o dominio funcional.

2. **Para cada endpoint, documentar:**

• **Método HTTP:** GET, POST, PUT, PATCH, DELETE.
• **Ruta:** con parámetros de ruta entre llaves (por ejemplo, `/users/{id}`).
• **Descripción:** qué hace este endpoint en una frase.
• **Autenticación:** qué tipo de autenticación requiere (Bearer token, API key, ninguna).
• **Parámetros de ruta:** nombre, tipo, descripción, si es obligatorio.
• **Parámetros de query:** nombre, tipo, descripción, valor por defecto.
• **Cuerpo de la petición (body):** esquema JSON con tipos, campos obligatorios y restricciones. Incluir ejemplo.
• **Respuestas:** para cada código de estado relevante, el esquema de la respuesta y un ejemplo.

3. **Cubrir los códigos de respuesta principales:**

| Código | Significado | Cuándo se devuelve | |--------|------------|-------------------| | 200 | OK | Petición exitosa (GET, PUT, PATCH) | | 201 | Created | Recurso creado exitosamente (POST) | | 204 | No Content | Operación exitosa sin cuerpo de respuesta (DELETE) | | 400 | Bad Request | Datos de entrada inválidos | | 401 | Unauthorized | Falta autenticación o token inválido | | 403 | Forbidden | Autenticado pero sin permisos | | 404 | Not Found | Recurso no existe | | 409 | Conflict | Conflicto con el estado actual (duplicado, versión desactualizada) | | 422 | Unprocessable Entity | Datos válidos pero no procesables por reglas de negocio | | 429 | Too Many Requests | Rate limit excedido | | 500 | Internal Server Error | Error inesperado del servidor |

4. **Incluir ejemplos con curl.** Para cada endpoint, al menos un ejemplo funcional:

   curl -X POST https://api.ejemplo.com/users \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"name": "Ana", "email": "ana@ejemplo.com"}'

5. **Documentar códigos de error personalizados.** Si la API devuelve errores con códigos propios, listarlos con su significado y la acción recomendada para el consumidor.

6. **Si se usa OpenAPI, generar el fichero de especificación.** Formato YAML o JSON compatible con OpenAPI 3.x. Incluir schemas reutilizables en `components/schemas`.

7. **Verificar la documentación contra el código.** Comprobar que cada endpoint documentado existe en el código y que los parámetros y respuestas coinciden. La documentación desactualizada es peor que no tener documentación.

Criterios de éxito

• Todos los endpoints públicos están documentados.
• Cada endpoint tiene método, ruta, parámetros, respuestas y al menos un ejemplo.
• Los códigos de error están documentados con su significado.
• Los ejemplos son funcionales (se podrían copiar y pegar para probar).
• La documentación está sincronizada con el código actual.