Saltar al contenido
Engineer
Menú
Diseño
Español

Engineer / Glosario

OpenAPI

descripción de una API HTTP legible por máquinas

Qué es

OpenAPI es un formato estándar para recoger todo lo que necesita saber quien llama a una API HTTP —direcciones, operaciones, entradas, salidas, errores y seguridad— en un único archivo JSON o YAML que pueden leer tanto personas como programas. El propio estándar es la OpenAPI Specification, a menudo abreviada como OAS, y un archivo escrito conforme a ella es una descripción OpenAPI. El formato empezó como Swagger Specification, y ese nombre anterior sobrevive en herramientas construidas a su alrededor, como Swagger UI.

La especificación dice que define una «descripción de interfaz estándar e independiente del lenguaje de programación para API HTTP». Su objetivo declarado es que una persona o un programa pueda saber qué hace un servicio sin su código fuente, documentación adicional ni una captura de su tráfico de red. Se recomienda llamar al documento de entrada openapi.json u openapi.yaml, y las descripciones grandes suelen repartirse entre varios archivos unidos por referencias.

Swagger 2.0 se publicó en septiembre de 2014 y se donó a la OpenAPI Initiative el 31 de diciembre de 2015. La versión 3.0.0 llegó en julio de 2017 con el nuevo nombre, la 3.1.0 en febrero de 2021 y la 3.2.0 en septiembre de 2025.

Una descripción tiene unas pocas partes de nivel superior. info da el nombre y la versión de la API; servers enumera dónde se ejecuta; paths contiene cada dirección y, bajo ella, una operación por método HTTP, con sus parámetros, cuerpo de petición y posibles respuestas. components reúne los elementos reutilizados: esquemas de datos, parámetros, respuestas y esquemas de seguridad que indican cómo se autentica quien llama. Desde la versión 3.1, una sección webhooks también puede describir las peticiones que la API envía a sus consumidores. Un fragmento mínimo:

openapi: 3.1.0
info:
    title: Orders
    version: 1.4.0
paths:
    /orders/{id}:
        get:
            operationId: getOrder
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
            responses:
                "200":
                    description: One order

Las estructuras de datos se escriben en un lenguaje de esquemas. Desde la versión 3.1, el objeto Schema es un superconjunto de JSON Schema Draft 2020-12; la 3.0 utilizaba un subconjunto ampliado de un borrador anterior, con añadidos propios. JSON Schema describe un elemento de datos, mientras que OpenAPI describe toda una API HTTP y toma prestado JSON Schema para sus partes. Sus vecinos describen otros tipos de interfaz: AsyncAPI cubre sistemas basados en mensajes, los servicios gRPC se declaran en archivos .proto de Protocol Buffers y un servidor GraphQL publica su propio esquema.

Por qué importa

Una descripción en un formato estándar es un archivo que muchas herramientas pueden leer, y cada una ahorra trabajo que un equipo haría a mano. La documentación de referencia se genera a partir de ella. También se generan bibliotecas cliente en varios lenguajes, de modo que un frontend llama a una función tipada en vez de montar una URL. Los servidores de simulación responden a partir de ella, así que puede construirse un frontend antes de que exista el backend. Las puertas de enlace importan sus rutas, las baterías de pruebas validan el tráfico contra ella y los agentes de IA que llaman a API la leen para saber qué se ofrece.

Ese alcance también es el riesgo. Todas esas herramientas confían en el archivo. Una descripción incorrecta es peor que ninguna, porque el cliente generado compila, la documentación parece una referencia autorizada y el error aparece durante la ejecución en el producto de otra persona.

Por tanto, la decisión principal es de dónde sale la descripción. En el enfoque que parte del diseño, las personas escriben la descripción, la revisan como contrato y después construyen el servidor para ajustarse a ella. La forma de la API se debate antes de que exista código, lo que encaja con API públicas y equipos que trabajan en paralelo. El coste es que la descripción y el servidor son dos cosas que pueden discrepar. En el enfoque que parte del código, la descripción se genera a partir de los tipos y las anotaciones del propio servidor. No puede describir una ruta que el servidor no tenga, pero solo puede ser tan precisa como esos tipos, y el debate de diseño ocurre en la revisión de código en vez de en un documento. En ambos casos, la descripción solo se mantiene fiel si una compilación la comprueba.

El paso de la versión 3.0 a la 3.1 cambió la forma de escribir esquemas, porque la 3.1 adoptó JSON Schema 2020-12. Generadores, validadores y puertas de enlace admiten cada uno su propio intervalo de versiones, así que la versión que escribe un equipo queda limitada por la herramienta más antigua de la cadena.

Cómo se aplica en la práctica

Al principio, Fiber alojaba una API con validación escrita a mano, endpoint por endpoint, y sin un documento único que describiera su estructura. La capa HTTP se migró a Huma v2, sobre Fiber, de modo que cada endpoint se declara con estructuras de entrada y salida y la descripción OpenAPI se genera a partir de esos tipos; la documentación sigue al código en vez de envejecer en una wiki. Los dos endpoints WebSocket permanecen en Fiber directamente, fuera del modelo de petición y respuesta de Huma. La escala explica la importancia de esa descripción: con 760 operaciones repartidas entre 649 rutas, es en la práctica la única forma de que alguien pueda leer la API, por lo que saber que está completa importa más que cuando tenía cincuenta. Una comprobación de CI mantiene la paridad de rutas en el 100 %.

En otro proyecto, la descripción es el eslabón intermedio de una cadena que parte de la base de datos hacia fuera. El esquema de la base de datos y sus funciones dan forma a los tipos Go; Huma emite la descripción y lo que utiliza el frontend se genera a partir de ella: un cliente TypeScript tipado de 44.076 líneas, 61 manejadores de simulación para las pruebas del frontend y los límites que aplica cada formulario. Aborda la divergencia entre frontend y backend, que suele manifestarse como un 422 en el navegador una vez publicado el desajuste. Una comprobación del contrato en CI hace fallar la compilación si hay divergencia, con una prueba dirigida a los campos opcionales del cuerpo, donde se confunden «ausente» y «null», y a las enumeraciones de parámetros de consulta. El coste es un paso de generación en medio de todo y una cadena tan fiable como su eslabón menos protegido.

La página de la empresa sobre preparación para agentes de IA aplica el mismo razonamiento a los agentes. Una aplicación que puedan utilizar ofrece una API descrita: un documento OpenAPI, un servidor MCP si se recomienda que los agentes la llamen directamente y metadatos OAuth para que un agente actúe por un usuario sin recibir su contraseña. La página clasifica cada recomendación en lugar de obedecerla sin más y, como el propio sitio de la empresa no tiene API, el catálogo de API y los metadatos OAuth son dos de las cinco que descartó para ese sitio.

Dónde surgen los problemas

La descripción promete algo que el servidor no hace. Una descripción mantenida a mano se queda atrás: un parámetro de consulta nuevo, un campo renombrado o un código de error que solo conoce el servidor. Los clientes generados compilan entonces contra una ficción. Genere la descripción desde el código o manténgala separada y valide peticiones y respuestas reales contra ella en la batería de pruebas, y compare las rutas que registra el servidor con las que enumera la descripción.

Cada regeneración del cliente cambia el nombre de la mitad de los métodos. Sin operationId, los generadores inventan nombres de métodos a partir de la ruta y del método HTTP, de modo que mover una ruta cambia el nombre de la función que utilizan todos sus consumidores. La especificación exige que cada operationId sea único y distingue mayúsculas de minúsculas. Asigne uno a cada operación, elíjalo con tanto cuidado como el nombre de una función pública y haga que un linter impida compilar si falta alguno.

Los campos que admiten null empiezan a rechazarlo tras una actualización. OpenAPI 3.0 los marcaba con nullable: true. En la versión 3.1 esa palabra clave desaparece y el tipo pasa a ser una lista; además, un validador suele ignorar una palabra clave que no conoce. Por tanto, un esquema 3.0 simplemente etiquetado como 3.1 rechaza null donde su autor quería permitirlo. Convierta los esquemas con la guía de actualización de la OpenAPI Initiative, que también explica cómo exclusiveMinimum pasa a ser un número:

# OpenAPI 3.0
type: string
nullable: true
---
# OpenAPI 3.1
type: [string, "null"]

Los ejemplos incumplen su propio esquema. La especificación dice que un ejemplo debería ajustarse a su esquema y deja la comprobación a las herramientas. Un lector copia el ejemplo de la documentación y obtiene un 422; un servidor de simulación lo sirve y el frontend se construye contra datos que la API real rechazará. Valide cada ejemplo en CI con el mismo rigor que el tráfico real.

La descripción pública revela la API de administración. Una única descripción generada desde todas las rutas y servida en una dirección pública enumera las operaciones internas y sus esquemas a cualquiera que la pida. Publique una descripción por público destinatario, generada con las operaciones internas excluidas. La especificación permite dejar objetos vacíos o eliminarlos precisamente para este tipo de control de acceso.

Lecturas adicionales

Contacto

¿Aún está definiendo lo que necesita?

Cuéntenos qué está fallando o qué intenta construir. Le diremos qué haría falta, cuánto costaría aproximadamente y si somos las personas adecuadas.

Desde 1.400 DKK por hora, sin IVA; y un precio por hora menor en una contratación más larga.

welcome@engineer.company +45 50 10 61 84 Copenhague, Dinamarca