686f6c61/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.