Mostrando solo ciertas propiedades de una referencia OpenAPI
No vi nada específico relacionado con esto en la Referencia de OpenAPI, así que quería preguntar aquí para confirmación.
Digamos que tengo una referencia con los siguientes datos:
components:
schemas:
Foobar:
type: object
properties:
timestamp:
type: number
uid:
type: number
username:
type: string
location:
type: string
¿Es posible referenciar este componente pero solo tomar propiedades específicas de él, como uid y username, y excluir el resto? Por ejemplo:
$ref: ''#/components/schemas/Foobar(uid,username)''
Mi caso de uso es que tengo una llamada de biblioteca que devuelve registros de la base de datos, agregando (o eliminando) registros adicionales según sea necesario en función de la entrada del usuario. Entonces, podríamos tener myCall(['username']); que devuelve solo el nombre de usuario, y myCall(['username', 'location']); que devuelve el nombre de usuario y la ubicación.
Si quisiera documentar correctamente los diferentes usos dentro de mi API, actualmente tendría que mantener manualmente todas las variantes diferentes de la salida.
Esperaba poder crear un componente “flexible” al que pudiera hacer referencia y aún así validarlo dentro de la especificación de OpenAPI.
Lo más cerca que he encontrado sería envolver todas las propiedades bajo anyOf:
components:
schemas:
Foobar:
anyOf:
- type: object
properties:
timestamp:
type: number
uid:
type: number
username:
type: string
location:
type: string
… pero si se analiza algo como ReDoc, simplemente mostraría que la salida puede ser cualquiera de las propiedades enumeradas, cuando en realidad necesito la capacidad de declarar que “de todas estas propiedades, se mostrarán las siguientes”.
Supongo que mi caso de uso es un poco esotérico, pero espero que me demuestren lo contrario 🙂
davy.ai
Basado en la especificación de OpenAPI, no es posible hacer referencia a un componente y seleccionar solo propiedades específicas dentro de él. La palabra clave
$refen OpenAPI se refiere al componente completo y no puede usarse para especificar propiedades individuales.Una posible solución alternativa sería definir componentes separados para cada combinación posible de propiedades, pero esto podría volverse complicado y difícil de mantener.
En cuanto a su caso de uso, podría ser más apropiado definir un solo componente que incluya todas las propiedades posibles, pero especificar en la documentación qué propiedades se incluirán según la entrada del usuario. Esto se puede hacer utilizando el campo
descriptiono anotaciones adicionales en el esquema.Como alternativa, podrías considerar definir múltiples componentes para cada variación potencial de salida y utilizar un mecanismo de cambio basado en el contexto para seleccionar el esquema adecuado en tiempo de ejecución.