CODEWITHSUNDEEP
swagger
tmesser
tmesser

Reputation: 7656

How do I denote a list of a specific object as a return in a Swagger file?

I'm attempting to document a REST API using Swagger. Per REST API norms, I have endpoints for each Thing, and the GET protocols for each endpoint are bog standard normal: /thing/{id} returns a single Thing with the matching ID you give, and /thing/ returns a list of all valid Things.

The YAML for /thing/{id} is straightforward enough.

get:
  operationId: GET_thing-id
  tags:
    - Thing
  description: >-
    Gets a specific Thing.
  parameters:
    - name: token
      in: query
      required: false
      type: string
    - name: Accept
      in: header
      required: false
      type: string
  responses:
    '200':
      description: ''
      schema:
        $ref: '#/definitions/Thing'

Where the $ref refers to the following, further down the YAML file:

definitions:
  Thing:
    title: Thing
    type: object
    properties:
      id:
        type: string
        description: uuid.

But I find myself unsure how to handle the /thing/ endpoint, which is supposed to simply return a list of the models above. There seems to be no clear way to do this from perusing the Swagger spec, which I have done in depth at this point. Does anyone have guidance on how to handle this?

Upvotes: 1

Views: 706

Answers (1)

tmesser
tmesser

Reputation: 7656

I figured it out. The problem was that there's slightly different things I need to define for an array and that was a real issue in tracking it down. The solution is:

definitions:
  ThingArray:
    title: ThingArray
    type: array
    items:
      $ref: '#/definitions/Thing'

This can then be used in the /thing/ path and it looks perfectly reasonable.

Upvotes: 3

Related Questions