api-docs

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": "[email protected]"}'
   

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.