Generador de OpenAPI
Generador de OpenAPI: convierte pares de método HTTP y ruta en un documento OpenAPI 3.0.3 mínimo.
Operaciones a partir de método y ruta
Cada línea contiene GET, POST, PUT, PATCH o DELETE y una ruta que empieza por /. El generador agrupa operaciones bajo paths y crea un documento OpenAPI 3.0.3 en JSON. Cada operación recibe una respuesta 200 mínima con descripción OK.
Parámetros entre llaves
Una ruta como /users/{id} genera un parámetro id situado en path, obligatorio y con schema string. La llave expresa la variable dentro de la ruta; el motor no deduce si debería ser número, UUID ni qué restricciones acepta.
Ejemplo de contrato inicial
GET /users/{id} crea paths./users/{id}.get y su parámetro requerido. Añadir POST /users produce otra operación bajo una ruta diferente. Abre el JSON en un editor OpenAPI y confirma que no haya combinaciones duplicadas de método y ruta.
Lo que debe completarse
Una API real necesita esquemas de respuesta, posibles errores, cuerpos, query, cabeceras, seguridad, servidores y ejemplos. La respuesta 200 vacía solo mantiene un documento inicial. No confundas validez estructural con una descripción suficiente para clientes o pruebas.
Diseño y validación posterior
La herramienta no consulta una API ni descubre endpoints. Usa la salida como esqueleto y decide nombres, operationId, tags y componentes con el equipo. Valida después contra OpenAPI 3.0.3 y prueba la documentación o generación de cliente que realmente consumirás.
Operaciones duplicadas y nombres estables
OpenAPI admite una operación por método dentro de cada ruta. Si repites GET /users, decide cuál definición conservar antes de ampliar el documento. Añadir operationId estables facilita clientes y enlaces, pero exige nombres únicos elegidos con criterio; el generador no puede deducirlos desde una ruta sin conocer el dominio. Declara también media types concretos, códigos de error y ejemplos verificables. Sin ellos, una interfaz puede renderizarse aunque un cliente generado desconozca qué enviar o recibir.
Fuentes y referencias
Continúa con estas herramientas
Preguntas frecuentes
¿Qué métodos acepta cada línea?
GET, POST, PUT, PATCH y DELETE. Deben preceder a una ruta que comience por barra.
¿Cómo detecta un parámetro de ruta?
Busca nombres entre llaves dentro del path y los declara requeridos con tipo string.
¿Genera requestBody para POST?
No. Crea la operación mínima, pero el cuerpo y su esquema deben añadirse según el contrato real.
¿La respuesta 200 describe datos reales?
No. Solo contiene una descripción básica. Añade content y schemas para representar el payload devuelto.
¿Puede importar endpoints desde un servidor?
No. Trabaja con las líneas escritas y no realiza descubrimiento ni peticiones de red.
¿El documento está en YAML o JSON?
La salida es JSON válido que representa OpenAPI 3.0.3. Puede convertirse después a YAML sin cambiar su estructura.
Herramienta de OCC Tools