Generador de Documentación API
Esta habilidad genera automáticamente documentación OpenAPI 3.0 (Swagger) a partir de archivos de rutas de API en tu base de código.
Cuándo Usar Esta Habilidad
- El usuario solicita generar documentación de API
- Trabajas con endpoints de API REST
- Necesitas crear o actualizar especificaciones OpenAPI/Swagger
- Configurar documentación de API para Express, FastAPI, Flask, NestJS o marcos similares
Instrucciones
1. Descubrir Rutas de API
Busca en la base de código definiciones de rutas de API:
- Express/Node.js: Busca
app.get(),app.post(),router.get(), etc. - FastAPI/Python: Busca decoradores
@app.get(),@router.post() - Flask: Busca decoradores
@app.route() - NestJS: Busca decoradores
@Get(),@Post(),@Controller() - Rails: Busca rutas en
config/routes.rb
Usa Glob para encontrar archivos de rutas (ej., **/*routes*.{js,ts,py}, **/controllers/**/*.{js,ts})
2. Analizar Patrones de Rutas
Para cada ruta descubierta, extrae:
- Método HTTP: GET, POST, PUT, PATCH, DELETE
- Ruta: La URL del endpoint (ej.,
/api/users/:id) - Parámetros: Parámetros de ruta, parámetros de consulta, cuerpo de la solicitud
- Respuesta: Estructura esperada de la respuesta
- Autenticación: Si se requiere autenticación
- Descripción: Comentarios o docstrings cerca de la ruta
3. Generar Especificación OpenAPI
Crea o actualiza un archivo de especificación OpenAPI 3.0 (normalmente openapi.yaml o swagger.json):
- Comienza con la plantilla de
templates/openapi-3.0.yaml - Mapea cada ruta a un objeto de ruta OpenAPI
- Define esquemas de solicitud/respuesta usando JSON Schema
- Incluye definiciones de parámetros (ruta, consulta, cuerpo)
- Agrega esquemas de autenticación si se detectan (Bearer, API Key, OAuth2)
- Agrupa endpoints por etiquetas (ej., "Usuarios", "Productos", "Autenticación")
4. Validar la Integridad
Verifica que la documentación generada incluya:
- Todos los endpoints descubiertos
- Métodos HTTP y rutas precisos
- Ejemplos de solicitud/respuesta cuando sea posible
- Respuestas de error (400, 401, 404, 500, etc.)
- Requisitos de seguridad
5. Ubicación de Salida
- Guarda como
openapi.yamlen la raíz del proyecto, o - Colócalo en el directorio
docs/oapi/si existen - Pregunta al usuario la ubicación preferida si no está claro
Notas Específicas del Marco
Express/Node.js
- Verifica el middleware de rutas que podría afectar la autenticación/validación
- Busca validadores de solicitudes (Joi, express-validator, etc.)
- Extrae comentarios JSDoc para descripciones de endpoints
FastAPI
- FastAPI genera automáticamente documentación OpenAPI, pero esta habilidad puede mejorarla
- Extrae modelos de Pydantic para esquemas de solicitud/respuesta
- Verifica los parámetros
response_modelystatus_code
NestJS
- Busca DTOs (Objetos de Transferencia de Datos) para esquemas
- Verifica decoradores de Swagger (
@ApiOperation,@ApiResponse) - Extrae metadatos de decoradores de controlador y método
Mejores Prácticas
- Usar esquemas existentes: Si la base de código tiene interfaces de TypeScript, modelos de Pydantic o similares, úsalos para esquemas precisos
- Incluir ejemplos: Agrega ejemplos de solicitud/respuesta de las pruebas si están disponibles
- Agrupar lógicamente: Organiza los endpoints por recurso o área de funcionalidad usando etiquetas
- Versión adecuada: Usa la versión de API de la base de código (ej., "1.0.0")
- Agregar descripciones: Usa comentarios/docstrings del código para descripciones de endpoints
Archivos de Soporte
templates/openapi-3.0.yaml: Plantilla base de OpenAPIexamples.md: Ejemplos específicos del marco