TL;DR
OpenAPI 3.1 añadió compatibilidad total con JSON Schema, webhooks y mejoras en el discriminador. OpenAPI 3.2 añadió soporte para el método QUERY, ejemplos mejorados y mejores definiciones de seguridad. Modern PetstoreAPI utiliza OpenAPI 3.2 para demostrar las últimas características con ejemplos listos para producción.
Introducción
Estás escribiendo una especificación OpenAPI. Ves referencias a OpenAPI 3.0, 3.1 y 3.2. ¿Cuál es la diferencia? ¿Deberías actualizar? ¿Tus herramientas soportarán la nueva versión?
OpenAPI ha evolucionado significativamente de 3.0 a 3.2. Cada versión añade características que hacen que las especificaciones de API sean más potentes y precisas. Pero no todas las herramientas soportan las últimas versiones, creando un desafío de compatibilidad.
El antiguo Swagger Petstore utiliza OpenAPI 2.0 (especificación Swagger). Modern PetstoreAPI utiliza OpenAPI 3.2, mostrando cada nueva característica con ejemplos listos para producción.
En esta guía, aprenderás qué cambió en cada versión de OpenAPI, cómo elegir la versión correcta y cómo Modern PetstoreAPI demuestra las características de OpenAPI 3.2.
Línea base de OpenAPI 3.0
OpenAPI 3.0 (lanzado en julio de 2017) fue una actualización importante de Swagger 2.0.
Características clave
1. Múltiples servidores
servers:
- url: https://api.petstoreapi.com/v1
description: Production
- url: https://staging.petstoreapi.com/v1
description: Staging
Swagger 2.0 solo soportaba un host.
2. Objeto cuerpo de la solicitud
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
Más claro que el parámetro body de Swagger 2.0.
3. Componentes para la reutilización
components:
schemas:
Pet:
type: object
responses:
NotFound:
description: Resource not found
parameters:
PetId:
name: petId
in: path
Mejor organización que las definitions de Swagger 2.0.
4. Callbacks
Define callbacks asíncronos (webhooks):
callbacks:
orderUpdate:
'{$request.body#/callbackUrl}':
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderUpdate'
5. Enlaces
Define relaciones entre operaciones:
links:
GetPetByPetId:
operationId: getPetById
parameters:
petId: '$response.body#/id'
Limitaciones
1. Incompatibilidad con JSON Schema
OpenAPI 3.0 utilizaba un subconjunto de JSON Schema Draft 5, no JSON Schema completo. Esto causaba problemas de validación.
2. No hay objeto webhooks
Los webhooks se definían como callbacks, lo que resultaba confuso.
3. Discriminador limitado
El soporte de polimorfismo era básico.
4. No hay tipo nulo
No se podía especificar type: null directamente.
Cambios importantes en OpenAPI 3.1
OpenAPI 3.1 (lanzado en febrero de 2021) se centró en la alineación con JSON Schema.
1. Compatibilidad total con JSON Schema 2020-12
El cambio más grande: Los esquemas de OpenAPI 3.1 son JSON Schema 2020-12 válidos.
Antes (OpenAPI 3.0):
type: string
nullable: true # Específico de OpenAPI
Después (OpenAPI 3.1):
type: [string, "null"] # JSON Schema estándar
Beneficios:
- Usa cualquier validador de JSON Schema
- Comparte esquemas entre OpenAPI y otras herramientas
- Acceso a todas las características de JSON Schema
2. Objeto Webhooks
Antes (OpenAPI 3.0):
# Webhooks definidos como callbacks (confuso)
paths:
/subscribe:
post:
callbacks:
orderUpdate:
# definición de webhook
Después (OpenAPI 3.1):
webhooks:
orderUpdate:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderUpdate'
Separación más clara entre los puntos finales de la API y los webhooks.
3. Discriminador mejorado
Mejor soporte de polimorfismo:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
discriminator:
propertyName: petType
mapping:
cat: '#/components/schemas/Cat'
dog: '#/components/schemas/Dog'
4. Identificador de licencia del objeto Info
info:
license:
name: MIT
identifier: MIT # Identificador SPDX
5. PathItem $ref
Referenciar ítems de ruta completos:
paths:
/pets:
$ref: '#/components/pathItems/PetsCollection'
Cambios que rompen la compatibilidad
1. Se eliminó nullable
Usa type: [string, "null"] en su lugar.
2. exclusiveMinimum/exclusiveMaximum cambiado
Ahora booleano, no numérico.
3. example vs examples
Validación más estricta.
Últimas características de OpenAPI 3.2
OpenAPI 3.2 (lanzado TBD, borrador disponible) añade patrones de API modernos.
1. Soporte para el método QUERY
Método HTTP QUERY para búsquedas complejas:
paths:
/pets/search:
query: # Nuevo método
requestBody:
content:
application/json:
schema:
type: object
properties:
filters:
type: object
sort:
type: array
responses:
'200':
description: Search results
Modern PetstoreAPI utiliza QUERY para búsquedas complejas de mascotas.
2. Ejemplos mejorados
Múltiples ejemplos con metadatos:
examples:
availableCat:
summary: Gato disponible
description: Un gato disponible para adopción
value:
id: "019b4132-70aa-764f-b315-e2803d882a24"
name: "Fluffy"
species: "CAT"
status: "AVAILABLE"
adoptedDog:
summary: Perro adoptado
value:
id: "019b4127-54d5-76d9-b626-0d4c7bfce5b6"
name: "Buddy"
species: "DOG"
status: "ADOPTED"
3. Definiciones de seguridad mejoradas
Mejor soporte de OAuth 2.0:
components:
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://petstoreapi.com/oauth/authorize
tokenUrl: https://petstoreapi.com/oauth/token
refreshUrl: https://petstoreapi.com/oauth/refresh
scopes:
pets:read: Leer mascotas
pets:write: Crear y actualizar mascotas
orders:read: Leer pedidos
4. Mapeo de discriminador mejorado
Polimorfismo más flexible:
discriminator:
propertyName: type
mapping:
cat: Cat
dog: Dog
bird: '#/components/schemas/Bird' # Puede mezclar local y $ref
5. Mejor soporte de depreciación
Depreciar campos específicos:
properties:
oldField:
type: string
deprecated: true
description: Usar newField en su lugar
newField:
type: string
Cómo Modern PetstoreAPI utiliza OpenAPI 3.2
Modern PetstoreAPI muestra cada característica de OpenAPI 3.2.
1. Especificación completa
La especificación completa de OpenAPI 3.2 está disponible en:
https://petstoreapi.com/openapi.json
2. Método QUERY para búsquedas complejas
/pets/search:
query:
summary: Buscar mascotas con criterios complejos
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PetSearchQuery'
3. Webhooks
webhooks:
petStatusChanged:
post:
summary: El estado de la mascota ha cambiado
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PetStatusWebhook'
4. Esquemas polimórficos
Pet:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Bird'
discriminator:
propertyName: species
5. Ejemplos completos
Cada endpoint incluye múltiples ejemplos que muestran diferentes escenarios.
6. Respuestas de error RFC 9457
responses:
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
Consulta la especificación completa de OpenAPI para ver todas las características.
Guía de migración
De 3.0 a 3.1
1. Reemplazar nullable:
# Antes
type: string
nullable: true
# Después
type: [string, "null"]
2. Actualizar exclusiveMinimum/exclusiveMaximum:
# Antes
minimum: 0
exclusiveMinimum: true
# Después
minimum: 0
exclusiveMinimum: 0
3. Mover webhooks:
# Antes
paths:
/subscribe:
callbacks:
# webhook
# Después
webhooks:
# webhook
De 3.1 a 3.2
1. Añadir métodos QUERY donde sea apropiado:
/pets/search:
query: # Nuevo en 3.2
# búsqueda compleja
2. Mejorar ejemplos:
examples:
example1:
summary: Descripción
value: {...}
3. Actualizar definiciones de seguridad:
Añadir refreshUrl a los flujos de OAuth.
Probando especificaciones OpenAPI con Apidog
Apidog soporta todas las versiones de OpenAPI.
Importar especificación OpenAPI
1. Abrir Apidog
2. Hacer clic en "Importar"
3. Seleccionar "OpenAPI 3.x"
4. Pegar URL o subir archivo
5. Apidog valida e importa
Validar especificación
Apidog comprueba:
- Validez del esquema
- Integridad de las referencias
- Corrección de los ejemplos
- Integridad de la definición de seguridad
Probar implementación de API
Generar casos de prueba a partir de la especificación:
- Validación de solicitudes
- Validación de respuestas
- Comprobaciones de código de estado
- Cumplimiento del esquema
Comparación de versiones
Importar múltiples versiones y comparar:
- Cambios que rompen la compatibilidad
- Nuevos endpoints
- Cambios en el esquema
- Campos obsoletos
Conclusión
OpenAPI ha evolucionado significativamente:
OpenAPI 3.0: Fundamentos con servidores, cuerpos de solicitud, callbacks
OpenAPI 3.1: Compatibilidad con JSON Schema, objeto webhooks, mejor polimorfismo
OpenAPI 3.2: Método QUERY, ejemplos mejorados, seguridad mejorada
Modern PetstoreAPI utiliza OpenAPI 3.2 para demostrar todas las características con ejemplos listos para producción. Es la implementación de referencia para el diseño de API moderno.
Usa Apidog para trabajar con cualquier versión de OpenAPI, validar especificaciones y probar implementaciones.
Preguntas frecuentes
¿Debo actualizar a OpenAPI 3.1 o 3.2?
Si tus herramientas lo soportan, sí. La compatibilidad de OpenAPI 3.1 con JSON Schema es valiosa. OpenAPI 3.2 añade patrones modernos como el método QUERY.
¿Mi especificación OpenAPI 3.0 funcionará con herramientas 3.1?
Mayormente sí, pero nullable y exclusiveMinimum/exclusiveMaximum necesitan actualizaciones.
¿Los generadores de código soportan OpenAPI 3.2?
El soporte está creciendo. Consulta la documentación de tu generador. Muchos soportan 3.1, menos soportan 3.2.
¿Puedo usar las características de OpenAPI 3.2 en 3.1?
No. Usa la versión que coincida con tus características. Si necesitas el método QUERY, usa 3.2.
¿Cómo valido mi especificación OpenAPI?
Usa Apidog para importar y validar tu especificación. Comprueba la validez del esquema y la integridad de las referencias.
¿Dónde puedo ver un ejemplo completo de OpenAPI 3.2?
Modern PetstoreAPI proporciona una especificación OpenAPI 3.2 completa y lista para producción.
¿Cuál es la diferencia entre webhooks y callbacks?
Los webhooks son solicitudes HTTP de servidor a cliente. Los callbacks se definen en OpenAPI 3.0 como parte de las operaciones. OpenAPI 3.1+ tiene un objeto webhooks dedicado.
¿Debo usar JSON o YAML para las especificaciones OpenAPI?
Ambos funcionan. YAML es más legible para humanos. JSON es más fácil para las herramientas. Modern PetstoreAPI proporciona ambos formatos.