Las claves verificadas
- OpenAPI describe rutas, operaciones, parámetros, respuestas y esquemas de una API HTTP en un documento estructurado. Ver evidencia
- La especificación permite reutilizar modelos mediante referencias y declarar tipos, restricciones y formatos. Ver evidencia
- Un documento OpenAPI puede servir como base para documentación, clientes y pruebas generadas por herramientas. Ver evidencia
- El contrato debe mantenerse alineado con el comportamiento real de la API para que las herramientas y los clientes no reciban información desactualizada. Ver evidencia
Qué es OpenAPI
OpenAPI es una especificación para describir una API HTTP con un documento estructurado. El archivo declara rutas, operaciones, parámetros, respuestas y esquemas de datos de una forma que pueden leer tanto las personas como las herramientas.
También puede servirte: Qué es un webhook y en qué se diferencia de una API
El documento funciona como un contrato del comportamiento expuesto. No implementa el servidor ni decide cómo se guarda la información, pero hace visible qué puede pedir un cliente, qué debe enviar y qué respuesta puede recibir.
Qué información puede describir
Una descripción OpenAPI puede incluir servidores, rutas y métodos como GET, POST, PUT o DELETE. También puede declarar parámetros de ruta y consulta, cuerpos de petición, códigos de respuesta, tipos de contenido y modelos reutilizables.
La especificación permite documentar esquemas con sus campos, tipos y restricciones. Las referencias evitan repetir el mismo modelo en cada endpoint y ayudan a que la documentación mantenga una forma coherente cuando crece la API.
Para qué sirve en un equipo
Un contrato compartido permite que backend y frontend acuerden una forma de integración antes de terminar todo el código. A partir del documento se pueden generar páginas de referencia, clientes de prueba, ejemplos y validaciones que señalen diferencias entre lo prometido y lo servido.
OpenAPI también ordena la conversación sobre errores y límites. Si una ruta responde 201 en un caso y 409 en otro, esos estados quedan declarados junto con sus cuerpos. La precisión reduce suposiciones que suelen aparecer cuando cada equipo mantiene una explicación propia.
Qué revisar antes de publicarlo
El contrato debe coincidir con el comportamiento real y distinguir campos obligatorios de opcionales. Revisá nombres, formatos, autenticación, códigos de error y ejemplos con la misma atención que el código; un documento incompleto puede generar clientes que compilan pero fallan al ejecutar.
Elegí una versión de la especificación y validá el archivo en cada cambio. Cuando una respuesta rompe a los clientes, documentá la nueva versión o una ruta de migración en vez de cambiar el significado en silencio. El contrato es útil cuando se mantiene junto con las decisiones del servicio.
Qué aporta VisteEsto: Nuestro trabajo en esta nota
VisteEsto organiza OpenAPI en cuatro usos concretos: describir rutas, compartir esquemas, generar ayudas de desarrollo y revisar cambios sin romper clientes.
Fuentes, actualizaciones y metodología 3 fuentes
Fuentes consultadas
- Fuente primariaOpenAPI Specification: Latest
- Fuente primariaSwagger Docs: OpenAPI Specification
- Fuente primariaOpenAPI Initiative: Learn the Specification
Historial de actualización
- Publicación inicial basada en la especificación oficial de OpenAPI, Swagger Docs y OpenAPI Initiative.
Cómo elaboramos esta nota
Definimos la consulta principal “qué es OpenAPI y para qué sirve”, contrastamos los datos con 3 fuentes —3 primarias— y revisamos contexto, imágenes y posibles vacíos antes de publicar. Conocé nuestra política editorial y de verificación.
