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

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

Felecia

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

Aflcio