How to document a response comprised of a list of resources using OpenAPI - rest

Question

I am trying to create OpenAPI yml documentation file (via swagger). One of my API calls returns a list of resources. Each resources has properties, a self link and a link to an additional link which will retrieve additional "stuff" which relate to the resource.
Please see the following example:
[
{
"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"
}
]
}
]
I am not sure what is the right way to document this, this is what I have in place right now.
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
But I do not believe this is adequately represents my API.
Thanks for your help

Answer 1

Links that are included in the actual response need to be described as part of the response body schema:
paths:
/foo/objects:
get:
operationId: getObject
responses:
'200':
description: Respresentation of objects
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/object'
components:
schemas:
object:
type: object
properties:
name:
type: string
links: # <-------------
type: array
items:
$ref: '#/components/schemas/link'
link:
type: object
properties:
rel:
type: string
href:
type: string
format: uri
OpenAPI 3.0 links concept is similar to HATEOAS, but not really. These links are used to describe how the values returned from one operation can be used as input in other operations. For example, the create user operation returns the user ID, and this ID can be used to update or delete the user. This page has some more info about the links keyword: https://swagger.io/docs/specification/links