{"canonical_url":"https://engineer.company/es/glossary/openapi/","content_markdown":"# OpenAPI\n\n## Qué es\n\nOpenAPI es un formato estándar para recoger todo lo que necesita saber quien\nllama a una API HTTP —direcciones, operaciones, entradas, salidas, errores y\nseguridad— en un único archivo JSON o YAML que pueden leer tanto personas como\nprogramas. El propio estándar es la OpenAPI Specification, a menudo abreviada\ncomo OAS, y un archivo escrito conforme a ella es una descripción OpenAPI. El\nformato empezó como Swagger Specification, y ese nombre anterior sobrevive en\nherramientas construidas a su alrededor, como Swagger UI.\n\nLa especificación dice que define una «descripción de interfaz estándar e\nindependiente del lenguaje de programación para API HTTP». Su objetivo declarado\nes que una persona o un programa pueda saber qué hace un servicio sin su código\nfuente, documentación adicional ni una captura de su tráfico de red. Se\nrecomienda llamar al documento de entrada `openapi.json` u `openapi.yaml`, y las descripciones grandes\nsuelen repartirse entre varios archivos unidos por referencias.\n\nSwagger 2.0 se publicó en septiembre de 2014 y se donó a la OpenAPI Initiative\nel 31 de diciembre de 2015. La versión 3.0.0 llegó en julio de 2017 con el nuevo\nnombre, la 3.1.0 en febrero de 2021 y la 3.2.0 en septiembre de 2025.\n\nUna descripción tiene unas pocas partes de nivel superior. `info` da el nombre y la\nversión de la API; `servers` enumera dónde se ejecuta; `paths` contiene cada dirección y,\nbajo ella, una operación por método HTTP, con sus parámetros, cuerpo de petición\ny posibles respuestas. `components` reúne los elementos reutilizados: esquemas de datos,\nparámetros, respuestas y esquemas de seguridad que indican cómo se autentica\nquien llama. Desde la versión 3.1, una sección `webhooks` también puede describir las\npeticiones que la API envía a sus consumidores. Un fragmento mínimo:\n\n```yaml\nopenapi: 3.1.0\ninfo:\n    title: Orders\n    version: 1.4.0\npaths:\n    /orders/{id}:\n        get:\n            operationId: getOrder\n            parameters:\n                - name: id\n                  in: path\n                  required: true\n                  schema:\n                      type: string\n            responses:\n                \"200\":\n                    description: One order\n```\n\nLas estructuras de datos se escriben en un lenguaje de esquemas. Desde la\nversión 3.1, el objeto Schema es un superconjunto de JSON Schema Draft 2020-12;\nla 3.0 utilizaba un subconjunto ampliado de un borrador anterior, con añadidos\npropios. JSON Schema describe un elemento de datos, mientras que OpenAPI\ndescribe toda una API HTTP y toma prestado JSON Schema para sus partes. Sus\nvecinos describen otros tipos de interfaz: AsyncAPI cubre sistemas basados en\nmensajes, los servicios gRPC se declaran en archivos `.proto` de [Protocol Buffers](https://protobuf.dev/) y un servidor\nGraphQL publica su propio esquema.\n\n## Por qué importa\n\nUna descripción en un formato estándar es un archivo que muchas herramientas\npueden leer, y cada una ahorra trabajo que un equipo haría a mano. La\ndocumentación de referencia se genera a partir de ella. También se generan\nbibliotecas cliente en varios lenguajes, de modo que un frontend llama a una\nfunción tipada en vez de montar una URL. Los servidores de simulación responden\na partir de ella, así que puede construirse un frontend antes de que exista el\nbackend. Las puertas de enlace importan sus rutas, las baterías de pruebas\nvalidan el tráfico contra ella y los agentes de IA que llaman a API la leen para\nsaber qué se ofrece.\n\nEse alcance también es el riesgo. Todas esas herramientas confían en el archivo.\nUna descripción incorrecta es peor que ninguna, porque el cliente generado\ncompila, la documentación parece una referencia autorizada y el error aparece\ndurante la ejecución en el producto de otra persona.\n\nPor tanto, la decisión principal es de dónde sale la descripción. En el enfoque\nque parte del diseño, las personas escriben la descripción, la revisan como\ncontrato y después construyen el servidor para ajustarse a ella. La forma de la\nAPI se debate antes de que exista código, lo que encaja con API públicas y\nequipos que trabajan en paralelo. El coste es que la descripción y el servidor\nson dos cosas que pueden discrepar. En el enfoque que parte del código, la\ndescripción se genera a partir de los tipos y las anotaciones del propio\nservidor. No puede describir una ruta que el servidor no tenga, pero solo puede\nser tan precisa como esos tipos, y el debate de diseño ocurre en la revisión de\ncódigo en vez de en un documento. En ambos casos, la descripción solo se\nmantiene fiel si una compilación la comprueba.\n\nEl paso de la versión 3.0 a la 3.1 cambió la forma de escribir esquemas, porque\nla 3.1 adoptó JSON Schema 2020-12. Generadores, validadores y puertas de enlace\nadmiten cada uno su propio intervalo de versiones, así que la versión que\nescribe un equipo queda limitada por la herramienta más antigua de la cadena.\n\n## Cómo se aplica en la práctica\n\nAl principio, Fiber alojaba una API con validación escrita a mano, endpoint por\nendpoint, y sin un documento único que describiera su estructura. La [capa HTTP se migró a Huma v2](/es/portfolio/migrated-the-api-to-huma-v2-at-100-parity/), sobre\nFiber, de modo que cada endpoint se declara con estructuras de entrada y salida\ny la descripción OpenAPI se genera a partir de esos tipos; la documentación\nsigue al código en vez de envejecer en una wiki. Los dos endpoints WebSocket\npermanecen en Fiber directamente, fuera del modelo de petición y respuesta de\nHuma. La escala explica la importancia de esa descripción: con 760 operaciones\nrepartidas entre 649 rutas, es en la práctica la única forma de que alguien\npueda leer la API, por lo que saber que está completa importa más que cuando\ntenía cincuenta. Una comprobación de CI mantiene la paridad de rutas en el 100\n%.\n\nEn otro proyecto, la descripción es el eslabón intermedio de una cadena que\nparte de la base de datos hacia fuera. El esquema de la base de datos y sus\nfunciones dan forma a los tipos Go; [Huma emite la descripción y lo que utiliza el frontend se genera a partir de ella](/es/portfolio/generated-the-api-contract-from-the-database-out/): un cliente TypeScript tipado de 44.076\nlíneas, 61 manejadores de simulación para las pruebas del frontend y los límites\nque aplica cada formulario. Aborda la divergencia entre frontend y backend,\nque suele manifestarse como un 422 en el navegador una vez publicado el\ndesajuste. Una comprobación del contrato en CI hace fallar la compilación si hay\ndivergencia, con una prueba dirigida a los campos opcionales del cuerpo, donde\nse confunden «ausente» y «null», y a las enumeraciones de parámetros de\nconsulta. El coste es un paso de generación en medio de todo y una cadena tan\nfiable como su eslabón menos protegido.\n\nLa [página de la empresa sobre preparación para agentes de IA](/es/ai-ready/) aplica el mismo razonamiento a los agentes. Una aplicación que puedan\nutilizar ofrece una API descrita: un documento OpenAPI, un servidor MCP si se recomienda que\nlos agentes la llamen directamente y metadatos OAuth para que un agente\nactúe por un usuario sin recibir su contraseña. La página clasifica cada\nrecomendación en lugar de obedecerla sin más y, como el propio sitio de la\nempresa no tiene API, el catálogo de API y los metadatos OAuth son dos de las\ncinco que descartó para ese sitio.\n\n## Dónde surgen los problemas\n\n**La descripción promete algo que el servidor no hace.** Una descripción\nmantenida a mano se queda atrás: un parámetro de consulta nuevo, un campo\nrenombrado o un código de error que solo conoce el servidor. Los clientes\ngenerados compilan entonces contra una ficción. Genere la descripción desde el\ncódigo o manténgala separada y valide peticiones y respuestas reales contra ella\nen la batería de pruebas, y compare las rutas que registra el servidor con las\nque enumera la descripción.\n\n**Cada regeneración del cliente cambia el nombre de la mitad de los métodos.**\nSin `operationId`, los generadores inventan nombres de métodos a partir de la ruta y del\nmétodo HTTP, de modo que mover una ruta cambia el nombre de la función que\nutilizan todos sus consumidores. La especificación exige que cada `operationId` sea único\ny distingue mayúsculas de minúsculas. Asigne uno a cada operación, elíjalo con\ntanto cuidado como el nombre de una función pública y haga que un linter impida\ncompilar si falta alguno.\n\n**Los campos que admiten null empiezan a rechazarlo tras una actualización.**\nOpenAPI 3.0 los marcaba con `nullable: true`. En la versión 3.1 esa palabra clave desaparece\ny el tipo pasa a ser una lista; además, un validador suele ignorar una palabra\nclave que no conoce. Por tanto, un esquema 3.0 simplemente etiquetado como 3.1\nrechaza null donde su autor quería permitirlo. Convierta los esquemas con la\nguía de actualización de la OpenAPI Initiative, que también explica cómo `exclusiveMinimum`\npasa a ser un número:\n\n```yaml\n# OpenAPI 3.0\ntype: string\nnullable: true\n---\n# OpenAPI 3.1\ntype: [string, \"null\"]\n```\n\n**Los ejemplos incumplen su propio esquema.** La especificación dice que un\nejemplo debería ajustarse a su esquema y deja la comprobación a las\nherramientas. Un lector copia el ejemplo de la documentación y obtiene un 422;\nun servidor de simulación lo sirve y el frontend se construye contra datos que\nla API real rechazará. Valide cada ejemplo en CI con el mismo rigor que el\ntráfico real.\n\n**La descripción pública revela la API de administración.** Una única\ndescripción generada desde todas las rutas y servida en una dirección pública\nenumera las operaciones internas y sus esquemas a cualquiera que la pida.\nPublique una descripción por público destinatario, generada con las operaciones\ninternas excluidas. La especificación permite dejar objetos vacíos o eliminarlos\nprecisamente para este tipo de control de acceso.\n\n## Lecturas adicionales\n\n- [Especificación OpenAPI](https://spec.openapis.org/oas/latest.html)\n  — versión más reciente del estándar, con la definición de cada objeto y campo\n  y el historial de cada publicación.\n- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12)\n  — lenguaje de esquemas que OpenAPI 3.1 y posteriores utilizan para cada cuerpo\n  de petición y respuesta.\n- [Actualización de OpenAPI 3.0 a 3.1](https://learn.openapis.org/upgrading/v3.0-to-v3.1.html)\n  — lista de cambios de esquemas de la propia OpenAPI Initiative, entre ellos\n  `nullable`.\n- [Huma: generación de OpenAPI](https://huma.rocks/features/openapi-generation/)\n  — cómo el marco Go utilizado en los proyectos anteriores deriva una\n  descripción de los tipos de los manejadores.\n\n\u003chttps://engineer.company/es/glossary/openapi/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"Qué es OpenAPI, cómo un archivo genera documentación, clientes y simulaciones, cuánto cuesta mantenerlo fiel y qué errores permiten que se desactualice.","formats":{"gemtext":"https://engineer.company/es/glossary/openapi/index.gmi","gopher":"https://engineer.company/es/glossary/openapi/gophermap","html":"https://engineer.company/es/glossary/openapi/","json":"https://engineer.company/es/glossary/openapi/index.json","markdown":"https://engineer.company/es/glossary/openapi/index.md","pdf":"https://engineer.company/es/glossary/openapi/index.pdf"},"kind":"page","language":"es","title":"¿Qué es OpenAPI?","url":"https://engineer.company/es/glossary/openapi/","version":1}