¿Qué hace openapi-spec-generation?
Genera y mantiene especificaciones OpenAPI 3.1 a partir de código, especificaciones design-first y patrones de validación. Útil al crear documentación de API, generar SDKs o garantizar el cumplimiento de contratos de API.
Descripción
Esta habilidad automatiza la creación y el mantenimiento de especificaciones OpenAPI 3.1, soportando tanto el enfoque code-first (análisis de código fuente como controladores, modelos y rutas) como el enfoque design-first (a partir de documentos de diseño). También permite validar especificaciones existentes contra patrones predefinidos o reglas de cumplimiento.
Plataformas Soportadas
- Claude Code
- Cursor
- Codex
Funcionalidades Clave
Generación desde Código
- Analiza controladores, modelos, rutas y esquemas de autenticación.
- Extrae endpoints, parámetros, tipos de datos y ejemplos de respuestas.
- Genera archivos YAML o JSON compatibles con OpenAPI 3.1.
Enfoque Design-First
- Interpreta documentos de diseño (p. ej., especificaciones escritas en Markdown o diagramas).
- Produce especificaciones OpenAPI completas y correctas.
Validación y Mantenimiento
- Verifica la consistencia de especificaciones existentes.
- Identifica errores comunes, como parámetros faltantes o tipos incorrectos.
- Actualiza especificaciones automáticamente cuando cambia el código.
Ejemplo de Uso
# Generar especificación desde código
openapi-specification generate --from-code ./src --output ./spec/openapi.yaml
# Validar especificación existente
openapi-specification validate --spec ./spec/openapi.yaml
Requisitos
- Node.js 18+ o Python 3.8+
- Acceso a Internet para descargar esquemas base (opcional)
Notas
- Asegúrate de que el código fuente esté correctamente estructurado para obtener resultados óptimos.
- Las especificaciones generadas siguen el estándar OpenAPI 3.1.0.
- Soporta autenticación mediante API Key, OAuth2 y JWT.