openapi-spec-generation
Generar especificaciones OpenAPI 3.1
Crear y mantener documentación de API consume tiempo y es propenso a errores. Esta skill proporciona plantillas completas, ejemplos de código y patrones de validación para especificaciones OpenAPI 3.1 para optimizar los flujos de trabajo de documentación de API.
Descargar el ZIP de la skill
Subir en Claude
Ve a Configuración → Capacidades → Skills → Subir skill
Activa y empieza a usar
Pruébalo
Usando "openapi-spec-generation". Crear una especificación OpenAPI para una API de catálogo de productos
Resultado esperado:
- openapi: 3.1.0 con sección info conteniendo title, description, version
- Endpoints GET/POST/PUT/DELETE para recurso products
- Esquema Product con propiedades id, name, price, description, category
- Parámetros de query para paginación y filtrado
- Respuestas de error para códigos de estado 400, 401, 404, 429
- Configuración de autenticación Bearer token en security schemes
Usando "openapi-spec-generation". Escribir reglas Spectral de validación para operation IDs
Resultado esperado:
- Regla verifica presencia de operationId en cada operación
- Nivel de severidad establecido en error para operationId faltante
- Valida que operationId siga patrón de convención de nombres
- Reporta violaciones con ruta del campo y mensaje descriptivo
Auditoría de seguridad
SeguroPure documentation skill containing YAML OpenAPI templates, code examples (Python FastAPI, TypeScript tsoa), and validation patterns. No executable code, no file system access, no network calls. All 126 static findings are false positives: detected cryptographic keywords are data format specifiers in YAML schemas, backticks are markdown formatting in documentation code blocks, URLs are example domains and documentation references, and system keywords are standard OpenAPI syntax.
Factores de riesgo
🌐 Acceso a red (13)
Puntuación de calidad
Lo que puedes crear
Crear especificaciones de API
Diseña y documenta APIs REST con plantillas completas de OpenAPI 3.1 incluyendo esquemas, ejemplos y esquemas de seguridad.
Documentación code-first
Genera specs de OpenAPI desde bases de código existentes de FastAPI o Express/tsoa para generación automática de SDK.
Validar contratos de API
Configura reglas de linting y pipelines de validación para asegurar que las especificaciones de API cumplan con estándares de calidad y conformidad.
Prueba estos prompts
Genera una plantilla de especificación OpenAPI 3.1 para una API de [RESOURCE] con endpoints CRUD, autenticación y respuestas de error.
Crea un ejemplo de código Python FastAPI que genere una especificación OpenAPI para gestión de usuarios con paginación y filtrado.
Escribe reglas de validación Spectral para specs de OpenAPI que enforce operation IDs, descripciones y definiciones de seguridad.
Genera un comando de OpenAPI Generator para crear un cliente TypeScript desde un archivo de especificación OpenAPI.
Mejores prácticas
- Usa $ref para esquemas, parámetros y respuestas reutilizables para mantener consistencia entre especificaciones
- Incluye ejemplos del mundo real en esquemas de request y response para ayudar a consumidores de API a entender el uso
- Define todas las respuestas de error posibles incluyendo errores de validación, fallos de autenticación y rate limiting
Evitar
- Evitar descripciones genéricas o faltantes en operaciones, parámetros y propiedades de esquema
- No omitir definir security schemes incluso para APIs internas
- Evitar hardcodear URLs de servidor en paths; usa variables de servidor para diferentes entornos
Preguntas frecuentes
¿Qué lenguajes de programación soporta esta skill?
¿Cuáles son los límites de tamaño para especificaciones OpenAPI?
¿Cómo integro con pipelines de CI/CD?
¿Se mantiene privada mi información de especificación de API?
¿Por qué mi especificación no genera los endpoints esperados?
¿Cómo se compara con Swagger Editor?
Detalles del desarrollador
Autor
wshobsonLicencia
MIT
Repositorio
https://github.com/wshobson/agents/tree/main/plugins/documentation-generation/skills/openapi-spec-generationRef.
main
Estructura de archivos
📄 SKILL.md