OpenAPI/Swagger: Array in the response

Question

I want to return a list of Activity's in a path. I tried to accive this by defining the Activity type in the items property:

#...
# intendation is not correct here
responses:
  '200':
    description: Successful response
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/responses/Activity'
#...
components:
  responses:
    Activity:
      description: Activity object
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: integer
                format: int64
              author_id:
                type: integer
                format: int64
              amount:
                type: integer
                format: int64
              activity_type:
                $ref: '#/components/schemas/ActivityType'
              start_time:
                type: string
                format: date
              end_time:
                type: string
                format: date

But this doesn't result in a list of Activities but in:

[
  "string"
]

How can I fix this/ implement a list of Activities as the return value? I already tried searching the documentation.

Answer 1

The response reference takes a Response Object which contains the properties such as content and description. The body or schema of the response object should either point to another schema object or it can be defined inline. In your case, pointing to #/components/schemas/... is the correct way to define your example with the type: array and items keywords defined, because you want a collection response

responses:
  '200':
    $ref: '#/components/responses/Activity_Response'
#...
components:
  schemas:
    Activity:
      description: Activity object
      schema:
        type: object
        properties:
          id:
            type: integer
            format: int64
          author_id:
            type: integer
            format: int64
          amount:
            type: integer
            format: int64
          activity_type:
            $ref: '#/components/schemas/ActivityType'
          start_time:
            type: string
            format: date
          end_time:
            type: string
            format: date
  responses:
    Activity_Response:
      description: Successful Activity response
      content:
        application/json:
          schema:
            type: array
            items:
              - $ref: '#/components/schemas/Activity'