Solución:
OpenAPI 3.1
Defina la propiedad como oneOf de El $ref y type: 'null'.
Versión YAML:
foo:
oneOf:
- type: 'null' # Note the quotes around 'null'
- $ref: '#/components/schemas/Foo'
Versión JSON:
"foo": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/components/schemas/Foo" }
]
}
OpenAPI 3.0
Versión YAML:
foo:
nullable: true
allOf:
- $ref: '#/components/schemas/Foo'
Versión JSON:
"foo": {
"nullable": true,
"allOf": [
{ "$ref": "#/components/schemas/Foo" }
]
}
En OAS 3.0, envolviendo $ref dentro allOf es necesario combinar el $ref con otras palabras clave, porque $ref sobrescribe las palabras clave del mismo nivel. Esto se analiza con más detalle en el repositorio de especificaciones de OpenAPI: los objetos de referencia no se combinan bien con “nullable”
No es fácil hacer eso. Incluso casi imposible. Sus opciones :
Esperar
Hay una discusión muy larga sobre este punto, tal vez algún día se haga …
Utilice extensiones de proveedores
Puede utilizar extensiones de proveedores como x-oneOf y x-anyOf. Ya lo he tomado por este camino difícil: debes actualizar todos usó ‘herramientas de arrogancia’ para tener en cuenta las extensiones de estos proveedores.
En mi caso, necesitábamos ‘solo’ para:
- Desarrolla nuestro propio analizador Jax-RS con anotaciones personalizadas para extraer el archivo API swagger de las fuentes
- Extiende swagger-codegen para tener en cuenta estas extensiones para generar código java para nuestros clientes
- Desarrolla nuestro propio swagger-ui: para facilitar este trabajo, agregamos un paso de preprocesamiento para convertir nuestro esquema swagger con nuestras extensiones a un esquema json válido. Es más fácil encontrar un módulo para representar esquemas json que esquemas swagger en javascript. Por contra, abandonamos la idea de probar la API con el botón ‘probarlo’.
Fue hace un año, tal vez ahora …
Refactorice sus API
Muchos proyectos no necesitan anyOf y oneOf, ¿por qué no nosotros?