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
- Identificar los endpoints a documentar. Revisar el código del proyecto para listar todas las rutas expuestas. Agruparlas por recurso o dominio funcional.
- 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.
- 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 |
- Incluir ejemplos con curl. Para cada endpoint, al menos un ejemplo funcional:
``bash curl -X POST https://api.ejemplo.com/users \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"name": "Ana", "email": "ana@ejemplo.com"}' ``
- 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.
- 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.
- 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.