{"schemaVersion":1,"id":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification","title":"OpenAPI 4.0 (Moonwalk): La Reescritura de Spec que Realmente Importa","description":"Nuevo mecanismo de overlays, webhooks de primera clase, workflows reutilizables, comparación con 3.1, y un path de migración real desde Swagger.","language":"es","datePublished":"2025-10-26","dateModified":null,"contentFormat":"text/markdown","content":"API Design\n\n# OpenAPI 4.0 (Moonwalk): La Reescritura de Spec que Realmente Importa\n\n2025-10-263 min lectura\n\nLucio Durán\nEngineering Manager & AI Solutions Architect\n\nTambién disponible en: [English](<https://lucioduran.com/blog/openapi-4-moonwalk-api-specification>)\n\n## El cambio estructural: de paths a requests\n\nEn [OpenAPI](<https://www.openapis.org/>) 3.1, la estructura top-level gira alrededor de ` paths `:\n\n```yaml\n# OpenAPI 3.1, centrado en paths\nopenapi: \"3.1.0\"\npaths:\n /users/{userId}:\n get:\n operationId: getUser\n parameters:\n - name: userId\n in: path\n required: true\n schema:\n type: string\n responses:\n \"200\":\n content:\n application/json:\n schema:\n $ref: \"#/components/schemas/User\"\n```\n\nOpenAPI 4.0 reorganiza alrededor de ` requests ` y ` pathItems `:\n\n```yaml\n# OpenAPI 4.0, centrado en requests\nopenapi: \"4.0.0\"\ninfo:\n title: User Service\n version: \"2.0\"\n\npathItems:\n user:\n parameters:\n userId:\n in: path\n schema:\n type: string\n requests:\n getUser:\n method: get\n outcomes:\n success:\n status: 200\n contentType: application/json\n body:\n schema:\n $ref: \"#/components/schemas/User\"\n notFound:\n status: 404\n contentType: application/problem+json\n body:\n schema:\n $ref: \"#/components/schemas/Problem\"\n\nurls:\n /users/{userId}: { $ref: \"#/pathItems/user\" }\n /v2/users/{userId}: { $ref: \"#/pathItems/user\" }\n```\n\nObservar varias cosas. Primero, los ` pathItems ` están desacoplados de las URLs. El mismo pathItem ` user ` sirve tanto ` /users/{userId} ` como ` /v2/users/{userId} `. Segundo, las responses ahora son ` outcomes `, resultados semánticos nombrados en vez de entradas indexadas por status code. ` success ` y ` notFound ` son más significativos que ` \"200\" ` y ` \"404\" `.\n\n## Overlays: capas sin forkear\n\nEsta es una feature largamente esperada. Los overlays te permiten tomar un documento base de OpenAPI y aplicar modificaciones sin editar el original:\n\n```yaml\n# base.yaml, tu spec canónica\nopenapi: \"4.0.0\"\ninfo:\n title: Payment API\n version: \"1.0\"\npathItems:\n charge:\n requests:\n createCharge:\n method: post\n body:\n schema:\n $ref: \"#/components/schemas/ChargeRequest\"\n outcomes:\n created:\n status: 201\n body:\n schema:\n $ref: \"#/components/schemas/Charge\"\nurls:\n /charges: { $ref: \"#/pathItems/charge\" }\n```\n\n```yaml\n# overlay-production.yaml\noverlay: \"1.0.0\"\nextends: base.yaml\nactions:\n - target: \"$.servers\"\n update:\n - url: https://api.example.com\n description: Production US-East\n - target: \"$.pathItems.charge.requests.createCharge\"\n update:\n security:\n - oauth2:\n scopes: [\"charges:write\"]\n```\n\nLa spec final se construye para cada ambiente:\n\n```bash\nredocly bundle base.yaml --overlay overlay-production.yaml -o production-spec.yaml\nredocly bundle base.yaml --overlay overlay-staging.yaml -o staging-spec.yaml\n```\n\nEsto elimina el patrón de \"copiar la spec y cambiar la URL del server\" que plaga toda API multi-ambiente.\n\n## Webhooks de primera clase\n\nEn 4.0 están integrados en el modelo de request/outcome:\n\n```yaml\nwebhooks:\n paymentCompleted:\n requests:\n notify:\n method: post\n contentType: application/json\n body:\n schema:\n type: object\n required: [event, data]\n properties:\n event:\n type: string\n const: payment.completed\n data:\n $ref: \"#/components/schemas/Payment\"\n outcomes:\n acknowledged:\n status: 200\n retry:\n status: [500, 502, 503]\n delivery:\n retryPolicy:\n maxRetries: 5\n backoff: exponential\n initialDelay: 30s\n signing:\n algorithm: hmac-sha256\n headerName: X-Webhook-Signature\n```\n\nLa sección ` delivery ` es nueva, documenta políticas de reintento y mecanismos de firmado como parte de la spec.\n\n## Migración desde 3.1\n\nLa migración de una spec de OpenAPI 3.1 de 2.400 líneas a 4.0 sigue este proceso:\n\n```bash\nnpx @redocly/cli transform openapi-3.1.yaml --to 4.0 -o openapi-4.0.yaml\nnpx @redocly/cli lint openapi-4.0.yaml --ruleset recommended\n```\n\nEl conversor automático maneja ~85% de la transformación. El 15% restante es nombrar outcomes semánticamente, extraer pathItems compartidos, y agregar metadata de delivery de webhooks.\n\n## Patrones de diseño de spec\n\n**Patrón: Outcomes de error compartidos**\n\n```yaml\ncomponents:\n outcomes:\n validationError:\n status: 422\n contentType: application/problem+json\n body:\n schema:\n $ref: \"#/components/schemas/ValidationProblem\"\n unauthorized:\n status: 401\n contentType: application/problem+json\n body:\n schema:\n $ref: \"#/components/schemas/AuthProblem\"\n\npathItems:\n charge:\n requests:\n createCharge:\n method: post\n outcomes:\n created:\n status: 201\n body:\n schema:\n $ref: \"#/components/schemas/Charge\"\n validation:\n $ref: \"#/components/outcomes/validationError\"\n auth:\n $ref: \"#/components/outcomes/unauthorized\"\n```\n\nOutcomes compartidos eliminan el problema de \"copiar error responses a cada endpoint\".\n\n## ¿Deberías migrar ahora?\n\nEvaluación honesta: para proyectos de API nuevos y tu toolchain soporta 4.0, usalo. Las mejoras estructurales hacen que las specs sean más fáciles de mantener a medida que crecen. Si teners una spec 3.1 grande que funciona bien, esperá 6-12 meses para que el tooling madure.\n\nLa mayor ganancia son los overlays. Pasar de mantener cuatro copias de una spec (dev, staging, prod, partner) a una base más cuatro archivos de overlay de 20 líneas representa una mejora significativa. Eso solo justifica el esfuerzo de migración.\n\n## Preguntas frecuentes\n\n### ¿Qué cambió de OpenAPI 3.1 a 4.0?\n\nLa estructura se reorganiza alrededor de 'requests' y 'outcomes' en vez de paths y operations. Los webhooks son ciudadanos de primera clase. Los overlays permiten capas de modificaciones. Los URL templates reemplazan los path patterns.\n\n### ¿OpenAPI 4.0 es backward compatible con 3.1?\n\nNo, es una reescritura estructural. Pero herramientas de migración automatizada manejan la mayor parte de la transformación. El modelo conceptual es lo suficientemente similar como para que la migración sea mecánica, no creativa.\n\n### ¿Debería migrar APIs existentes a 4.0?\n\nNo inmediatamente. Esperá a que el tooling madure, generadores de código, validadores y renderers de documentación necesitan ponerse al día. Para APIs nuevas, vale la pena adoptar 4.0 si tu toolchain lo soporta.\n\n## Tips\n\n1. **Tip:** Iniciar con Overlays antes de migrar tu spec completa a 4.0. Puede mantener tu 3.1 como fuente de verdad y agregar detalles por ambiente (server URLs, esquemas de auth) con archivos ` overlay.yaml `.\n2. **Tip:** Utilizar ` pathItems ` en vez del viejo objeto ` paths ` cuando construyas patrones compartidos. Una sola definición de pathItem puede referenciarse desde múltiples URL templates.\n3. **Tip:** Validá tu spec 4.0 con ` @redocly/cli lint ` antes de confiar en generadores de código. La mayoría de los generadores van 3-6 meses atrás de la spec.\n\n- openapi\n- moonwalk\n- api-design\n- api-specification\n- webhooks\n- swagger\n- rest-api\n- api-gateway\n\n[Volver al Blog](<https://lucioduran.com/es/blog>)","headings":[{"level":1,"text":"OpenAPI 4.0 (Moonwalk): La Reescritura de Spec que Realmente Importa","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#title"},{"level":2,"text":"El cambio estructural: de paths a requests","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#el-cambio-estructural-de-paths-a-requests"},{"level":2,"text":"Overlays: capas sin forkear","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#overlays-capas-sin-forkear"},{"level":2,"text":"Webhooks de primera clase","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#webhooks-de-primera-clase"},{"level":2,"text":"Migración desde 3.1","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#migracin-desde-31"},{"level":2,"text":"Patrones de diseño de spec","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#patrones-de-diseo-de-spec"},{"level":2,"text":"¿Deberías migrar ahora?","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#deberas-migrar-ahora"},{"level":2,"text":"Preguntas frecuentes","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#questions"},{"level":3,"text":"¿Qué cambió de OpenAPI 3.1 a 4.0?","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#question-1"},{"level":3,"text":"¿OpenAPI 4.0 es backward compatible con 3.1?","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#question-2"},{"level":3,"text":"¿Debería migrar APIs existentes a 4.0?","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#question-3"},{"level":2,"text":"Tips","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#article-tips"}],"sections":[{"heading":"OpenAPI 4.0 (Moonwalk): La Reescritura de Spec que Realmente Importa","level":1,"url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification","content":"API Design"},{"heading":"OpenAPI 4.0 (Moonwalk): La Reescritura de Spec que Realmente Importa","level":1,"url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#title","content":"2025-10-263 min lectura\n\nLucio Durán\nEngineering Manager & AI Solutions Architect\n\nTambién disponible en: [English](<https://lucioduran.com/blog/openapi-4-moonwalk-api-specification>)"},{"heading":"El cambio estructural: de paths a requests","level":2,"url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#el-cambio-estructural-de-paths-a-requests","content":"En [OpenAPI](<https://www.openapis.org/>) 3.1, la estructura top-level gira alrededor de ` paths `:\n\n```yaml\n# OpenAPI 3.1, centrado en paths\nopenapi: \"3.1.0\"\npaths:\n /users/{userId}:\n get:\n operationId: getUser\n parameters:\n - name: userId\n in: path\n required: true\n schema:\n type: string\n responses:\n \"200\":\n content:\n application/json:\n schema:\n $ref: \"#/components/schemas/User\"\n```\n\nOpenAPI 4.0 reorganiza alrededor de ` requests ` y ` pathItems `:\n\n```yaml\n# OpenAPI 4.0, centrado en requests\nopenapi: \"4.0.0\"\ninfo:\n title: User Service\n version: \"2.0\"\n\npathItems:\n user:\n parameters:\n userId:\n in: path\n schema:\n type: string\n requests:\n getUser:\n method: get\n outcomes:\n success:\n status: 200\n contentType: application/json\n body:\n schema:\n $ref: \"#/components/schemas/User\"\n notFound:\n status: 404\n contentType: application/problem+json\n body:\n schema:\n $ref: \"#/components/schemas/Problem\"\n\nurls:\n /users/{userId}: { $ref: \"#/pathItems/user\" }\n /v2/users/{userId}: { $ref: \"#/pathItems/user\" }\n```\n\nObservar varias cosas. Primero, los ` pathItems ` están desacoplados de las URLs. El mismo pathItem ` user ` sirve tanto ` /users/{userId} ` como ` /v2/users/{userId} `. Segundo, las responses ahora son ` outcomes `, resultados semánticos nombrados en vez de entradas indexadas por status code. ` success ` y ` notFound ` son más significativos que ` \"200\" ` y ` \"404\" `."},{"heading":"Overlays: capas sin forkear","level":2,"url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#overlays-capas-sin-forkear","content":"Esta es una feature largamente esperada. Los overlays te permiten tomar un documento base de OpenAPI y aplicar modificaciones sin editar el original:\n\n```yaml\n# base.yaml, tu spec canónica\nopenapi: \"4.0.0\"\ninfo:\n title: Payment API\n version: \"1.0\"\npathItems:\n charge:\n requests:\n createCharge:\n method: post\n body:\n schema:\n $ref: \"#/components/schemas/ChargeRequest\"\n outcomes:\n created:\n status: 201\n body:\n schema:\n $ref: \"#/components/schemas/Charge\"\nurls:\n /charges: { $ref: \"#/pathItems/charge\" }\n```\n\n```yaml\n# overlay-production.yaml\noverlay: \"1.0.0\"\nextends: base.yaml\nactions:\n - target: \"$.servers\"\n update:\n - url: https://api.example.com\n description: Production US-East\n - target: \"$.pathItems.charge.requests.createCharge\"\n update:\n security:\n - oauth2:\n scopes: [\"charges:write\"]\n```\n\nLa spec final se construye para cada ambiente:\n\n```bash\nredocly bundle base.yaml --overlay overlay-production.yaml -o production-spec.yaml\nredocly bundle base.yaml --overlay overlay-staging.yaml -o staging-spec.yaml\n```\n\nEsto elimina el patrón de \"copiar la spec y cambiar la URL del server\" que plaga toda API multi-ambiente."},{"heading":"Webhooks de primera clase","level":2,"url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#webhooks-de-primera-clase","content":"En 4.0 están integrados en el modelo de request/outcome:\n\n```yaml\nwebhooks:\n paymentCompleted:\n requests:\n notify:\n method: post\n contentType: application/json\n body:\n schema:\n type: object\n required: [event, data]\n properties:\n event:\n type: string\n const: payment.completed\n data:\n $ref: \"#/components/schemas/Payment\"\n outcomes:\n acknowledged:\n status: 200\n retry:\n status: [500, 502, 503]\n delivery:\n retryPolicy:\n maxRetries: 5\n backoff: exponential\n initialDelay: 30s\n signing:\n algorithm: hmac-sha256\n headerName: X-Webhook-Signature\n```\n\nLa sección ` delivery ` es nueva, documenta políticas de reintento y mecanismos de firmado como parte de la spec."},{"heading":"Migración desde 3.1","level":2,"url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#migracin-desde-31","content":"La migración de una spec de OpenAPI 3.1 de 2.400 líneas a 4.0 sigue este proceso:\n\n```bash\nnpx @redocly/cli transform openapi-3.1.yaml --to 4.0 -o openapi-4.0.yaml\nnpx @redocly/cli lint openapi-4.0.yaml --ruleset recommended\n```\n\nEl conversor automático maneja ~85% de la transformación. El 15% restante es nombrar outcomes semánticamente, extraer pathItems compartidos, y agregar metadata de delivery de webhooks."},{"heading":"Patrones de diseño de spec","level":2,"url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#patrones-de-diseo-de-spec","content":"**Patrón: Outcomes de error compartidos**\n\n```yaml\ncomponents:\n outcomes:\n validationError:\n status: 422\n contentType: application/problem+json\n body:\n schema:\n $ref: \"#/components/schemas/ValidationProblem\"\n unauthorized:\n status: 401\n contentType: application/problem+json\n body:\n schema:\n $ref: \"#/components/schemas/AuthProblem\"\n\npathItems:\n charge:\n requests:\n createCharge:\n method: post\n outcomes:\n created:\n status: 201\n body:\n schema:\n $ref: \"#/components/schemas/Charge\"\n validation:\n $ref: \"#/components/outcomes/validationError\"\n auth:\n $ref: \"#/components/outcomes/unauthorized\"\n```\n\nOutcomes compartidos eliminan el problema de \"copiar error responses a cada endpoint\"."},{"heading":"¿Deberías migrar ahora?","level":2,"url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#deberas-migrar-ahora","content":"Evaluación honesta: para proyectos de API nuevos y tu toolchain soporta 4.0, usalo. Las mejoras estructurales hacen que las specs sean más fáciles de mantener a medida que crecen. Si teners una spec 3.1 grande que funciona bien, esperá 6-12 meses para que el tooling madure.\n\nLa mayor ganancia son los overlays. Pasar de mantener cuatro copias de una spec (dev, staging, prod, partner) a una base más cuatro archivos de overlay de 20 líneas representa una mejora significativa. Eso solo justifica el esfuerzo de migración."},{"heading":"Preguntas frecuentes","level":2,"url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#questions","content":""},{"heading":"¿Qué cambió de OpenAPI 3.1 a 4.0?","level":3,"url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#question-1","content":"La estructura se reorganiza alrededor de 'requests' y 'outcomes' en vez de paths y operations. Los webhooks son ciudadanos de primera clase. Los overlays permiten capas de modificaciones. Los URL templates reemplazan los path patterns."},{"heading":"¿OpenAPI 4.0 es backward compatible con 3.1?","level":3,"url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#question-2","content":"No, es una reescritura estructural. Pero herramientas de migración automatizada manejan la mayor parte de la transformación. El modelo conceptual es lo suficientemente similar como para que la migración sea mecánica, no creativa."},{"heading":"¿Debería migrar APIs existentes a 4.0?","level":3,"url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#question-3","content":"No inmediatamente. Esperá a que el tooling madure, generadores de código, validadores y renderers de documentación necesitan ponerse al día. Para APIs nuevas, vale la pena adoptar 4.0 si tu toolchain lo soporta."},{"heading":"Tips","level":2,"url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#article-tips","content":"1. **Tip:** Iniciar con Overlays antes de migrar tu spec completa a 4.0. Puede mantener tu 3.1 como fuente de verdad y agregar detalles por ambiente (server URLs, esquemas de auth) con archivos ` overlay.yaml `.\n2. **Tip:** Utilizar ` pathItems ` en vez del viejo objeto ` paths ` cuando construyas patrones compartidos. Una sola definición de pathItem puede referenciarse desde múltiples URL templates.\n3. **Tip:** Validá tu spec 4.0 con ` @redocly/cli lint ` antes de confiar en generadores de código. La mayoría de los generadores van 3-6 meses atrás de la spec.\n\n- openapi\n- moonwalk\n- api-design\n- api-specification\n- webhooks\n- swagger\n- rest-api\n- api-gateway\n\n[Volver al Blog](<https://lucioduran.com/es/blog>)"}],"links":[{"text":"English","url":"https://lucioduran.com/blog/openapi-4-moonwalk-api-specification"},{"text":"OpenAPI","url":"https://www.openapis.org/"},{"text":"Volver al Blog","url":"https://lucioduran.com/es/blog"}],"structuredData":[{"@context":"https://schema.org","@graph":[{"@type":"BlogPosting","@id":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification#article","mainEntityOfPage":{"@type":"WebPage","@id":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification"},"headline":"OpenAPI 4.0 (Moonwalk): La Reescritura de Spec que Realmente Importa","description":"Nuevo mecanismo de overlays, webhooks de primera clase, workflows reutilizables, comparación con 3.1, y un path de migración real desde Swagger.","datePublished":"2025-10-26","author":{"@type":"Person","@id":"https://lucioduran.com/#person","name":"Lucio Durán","url":"https://lucioduran.com"},"publisher":{"@type":"Person","@id":"https://lucioduran.com/#person","name":"Lucio Durán","url":"https://lucioduran.com"},"image":"https://lucioduran.com/favicons/og-default.png","url":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification","inLanguage":"es","isPartOf":{"@id":"https://lucioduran.com/blog#blog"},"articleSection":"API Design","keywords":"openapi, moonwalk, api-design, api-specification, webhooks, swagger, rest-api, api-gateway","wordCount":578,"timeRequired":"PT3M","workTranslation":[{"@type":"BlogPosting","inLanguage":"en","url":"https://lucioduran.com/blog/openapi-4-moonwalk-api-specification"}]},{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Inicio","item":"https://lucioduran.com/"},{"@type":"ListItem","position":2,"name":"Blog","item":"https://lucioduran.com/es/blog"},{"@type":"ListItem","position":3,"name":"OpenAPI 4.0 (Moonwalk): La Reescritura de Spec que Realmente Importa","item":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification"}]},{"@type":"FAQPage","mainEntity":[{"@type":"Question","name":"¿Qué cambió de OpenAPI 3.1 a 4.0?","acceptedAnswer":{"@type":"Answer","text":"La estructura se reorganiza alrededor de 'requests' y 'outcomes' en vez de paths y operations. Los webhooks son ciudadanos de primera clase. Los overlays permiten capas de modificaciones. Los URL templates reemplazan los path patterns."}},{"@type":"Question","name":"¿OpenAPI 4.0 es backward compatible con 3.1?","acceptedAnswer":{"@type":"Answer","text":"No, es una reescritura estructural. Pero herramientas de migración automatizada manejan la mayor parte de la transformación. El modelo conceptual es lo suficientemente similar como para que la migración sea mecánica, no creativa."}},{"@type":"Question","name":"¿Debería migrar APIs existentes a 4.0?","acceptedAnswer":{"@type":"Answer","text":"No inmediatamente. Esperá a que el tooling madure, generadores de código, validadores y renderers de documentación necesitan ponerse al día. Para APIs nuevas, vale la pena adoptar 4.0 si tu toolchain lo soporta."}}]}]}],"contentHash":"b1d8aba23ea158ea0c20f7409ece2c151a382497093bb5a9d9dd383e37145270","provenance":{"method":"Deterministic serialization of the server-rendered main element","source":"https://lucioduran.com/es/blog/openapi-4-moonwalk-api-specification","hashAlgorithm":"sha256","hashScope":"JSON document fields before contentHash and provenance","sourceHTMLBytes":48458,"contentBytes":6871}}