Cómo documentar una respuesta comprometida de una lista de recursos usando OpenAPI
Estoy tratando de crear el archivo de documentación OpenAPI yml (a través de swagger). Una de mis llamadas API devuelve una lista de recursos. Cada recurso tiene propiedades, un enlace propio y un enlace a un enlace adicional que recuperará "cosas" adicionales relacionadas con el recurso.
Por favor vea el siguiente ejemplo:
[
{
"name": "object-01",
"links": [
{
"rel": "self",
"href": "http://localhost:8800/foo/object-01"
},
{
"rel": "Supported stuff",
"href": "http://localhost:8800/foo/object-01/stuff"
}
]
}, {
"name": "object-02",
"links": [
{
"rel": "self",
"href": "http://localhost:8800/foo/object-02"
},
{
"rel": "Supported stuff",
"href": "http://localhost:8800/foo/object-02/stuff"
}
]
}, {
"name": "object-03",
"links": [
{
"rel": "self",
"href": "http://localhost:8800/foo/object-03"
},
{
"rel": "Supported stuff",
"href": "http://localhost:8800/foo/object-03/stuff"
}
]
}
]
No estoy seguro de cuál es la forma correcta de documentar esto, esto es lo que tengo en este momento.
paths:
/foo/objects:
get:
operationId: getObject
responses:
'200':
description: Respresentation of objects
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/object'
links:
self:
$ref: '#/components/links/object'
components:
links:
object:
operationId: getSObject
stuff:
operationId: getStuff
schemas:
object:
type: object
properties:
name:
type: string
Pero no creo que esto represente adecuadamente mi API.
Gracias por tu ayuda