Generador de esquemas de respuesta JSON a OpenAPI
Infiere un esquema de respuesta a partir de muestras JSON y genera una ruta YAML OpenAPI 3.0.3.
Cómo funciona
Pega una muestra JSON de respuesta, introduce una ruta literal y elige GET, POST, PUT o DELETE. El generador infiere un esquema del cuerpo de respuesta y lo coloca en un documento YAML OpenAPI 3.0.3.
Usa muestras representativas para mostrar las variaciones posibles de la respuesta. Si hay varios objetos en la misma ubicación de una matriz, el generador combina sus propiedades y solo marca una propiedad como obligatoria cuando aparece en cada objeto observado.
Revisa los tipos inferidos y los campos obligatorios antes de usar el YAML. Añade por tu cuenta cuerpos de solicitud, parámetros, autenticación, respuestas de error y declaraciones de parámetros de ruta. Después valida el documento completo con un validador OpenAPI.
Usa esta herramienta cuando tengas ejemplos JSON, pero no un esquema de respuesta. Solo documenta la ruta y el método seleccionados a partir de la muestra proporcionada.
Paso a paso
- Pega una muestra JSON de respuesta
- Indica una ruta literal y elige el método
- Revisa y copia el esquema de respuesta
Ejemplo desarrollado
Para GET /api/users, pega {"user":{"id":7,"name":"Ada"},"tags":["vip",null,7],"metrics":[{"count":2,"score":1.5},{"count":3,"active":true}]}. La muestra contiene objetos anidados, valores mixtos en una matriz y dos objetos de métricas.
La salida marca user, tags y metrics como obligatorios. Ambos objetos de métricas contienen count, por lo que también es obligatorio. score y active aparecen en un solo objeto cada uno, así que son opcionales. tags admite una cadena o un entero; ambos tipos observados son anulables porque la muestra también contiene null.
Cuándo usar esta herramienta
Usa el generador para convertir cuerpos JSON de respuesta de ejemplo en un esquema OpenAPI inicial al documentar una ruta.
Sirve para organizar las formas de respuesta observadas. El documento generado aún necesita los detalles de solicitud, seguridad, errores y parámetros de tu API.
Errores habituales
Un solo objeto hace que todas las propiedades incluidas parezcan obligatorias. Para identificar propiedades que varían entre respuestas, proporciona varios objetos representativos en la misma ubicación de una matriz.
No trates la salida inferida como una definición API completa. Comprueba el tratamiento de null, los campos opcionales, las variantes de matrices y las rutas literales. Añade los detalles de solicitudes y errores que quedan fuera del alcance de esta herramienta.
Reglas de inferencia
Para cada ubicación de objeto, claves obligatorias = claves presentes en todos los objetos observados.
Para cada valor, esquema inferido = unión de los tipos no nulos observados.
Si se observa null junto con un tipo conocido, ese esquema tipado se marca como anulable.
Esta inferencia se basa en muestras y no comprueba un contrato en ejecución. Un solo ejemplo no permite saber qué campos pueden faltar en las respuestas de producción.
Limitaciones y supuestos
El resultado describe los valores observados en la muestra. No puede identificar campos ausentes en todos los ejemplos, demostrar que un campo sea opcional en producción ni inferir el tipo de elemento de una matriz vacía. Un valor que solo aparece como null no tiene tipo inferible. Los valores mixtos se representan como alternativas y quizá debas compararlos con el contrato de tu API.
Términos clave
- Documento OpenAPI
- Un documento OpenAPI describe las rutas, operaciones, entradas, respuestas y otros detalles de una API en un formato legible por máquinas.
- Esquema
- Un esquema describe la estructura y los tipos de valores esperados, por ejemplo, un objeto con propiedades con nombre.
- Propiedad obligatoria
- En esta salida, obligatorio significa que la propiedad apareció en todos los objetos observados en esa ubicación. No demuestra el comportamiento en producción.
Comparar herramientas relacionadas
Usa el convertidor de YAML a JSON para obtener JSON a partir de una entrada YAML compatible. Usa SQL a TypeScript para obtener tipos de TypeScript desde una definición de tabla. Esta herramienta infiere un esquema de respuesta a partir de muestras JSON.
El generador de datos simulados para API crea filas a partir de un objeto JSON de ejemplo. Esta herramienta infiere un esquema de respuesta a partir de una muestra JSON y no genera datos simulados.
Preguntas frecuentes
¿Cómo se convierte la muestra en un esquema de respuesta?
El generador inspecciona todos los valores de la muestra JSON. Crea propiedades de objeto, examina todos los elementos de las matrices y combina los tipos observados con anyOf cuando hace falta. Por ejemplo, la matriz tags del ejemplo contiene cadenas, null y un entero, así que el esquema de sus elementos permite una cadena anulable o un entero anulable.
¿Cómo se representan null y los tipos distintos?
Los objetos se convierten en esquemas con propiedades. Una propiedad se marca como obligatoria cuando aparece en todos los objetos observados en esa ubicación. Los valores con distintos tipos observados usan anyOf. Si se observa null junto con otro tipo, el esquema tipado recibe nullable: true. Un valor que solo aparece como null no tiene un tipo inferible y su esquema queda sin restricciones.
¿Qué incluye el documento generado?
El documento contiene una ruta, el método seleccionado GET, POST, PUT o DELETE y una respuesta JSON correcta con estado 200. El esquema se guarda en components y se referencia desde la respuesta. El generador no crea un cuerpo de solicitud, parámetros, reglas de seguridad, respuestas de error ni encabezados.
¿Puedo introducir un parámetro de ruta como un ID?
La ruta debe ser literal y empezar por una barra, como /api/users. Se rechazan las rutas con llaves porque una plantilla como /api/users/{id} también necesita un parámetro de ruta declarado, que este generador no añade.
¿Genera o valida un contrato API completo?
No. La salida describe el cuerpo de una respuesta de ejemplo. No infiere esquemas de solicitud ni valida el YAML generado frente a la especificación OpenAPI. Añade las demás operaciones y detalles de respuesta y después comprueba el documento completo con un validador OpenAPI.
Herramientas relacionadas
El convertidor de YAML a JSON convierte entradas YAML compatibles a JSON. SQL a TypeScript obtiene declaraciones de tipos a partir de estructuras SQL. El generador de datos simulados para API crea filas a partir de un objeto JSON de ejemplo. Esta herramienta infiere un esquema de respuesta a partir de muestras JSON.