Swagger OAS3.0 Multiple responses in the same response code

Question

I am using Swagger Hub to generate API and wanting to get multiple responses for the get request: https://virtserver.swaggerhub.com/factly/test/1.0.0/categories

Following is how I defined my API. When I execute the API I only get one category in response. How do I get all the three categories defined as a response? Any help is greatly appreciated.

openapi: 3.0.0
info:
  description: This is the sample API for Core
  version: "1.0.0"
  title: Dega Core API
tags:
  - name: Core
    description: Operations related to Core
paths:
  /categories:
    get:
      tags:
        - Core
      summary: gets all the categories
      description: this is to get all the available categories
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryItem'
              examples:
                category1:
                  $ref: '#/components/examples/category1'
                category2:
                  $ref: '#/components/examples/category2' 
                category3:
                  $ref: '#/components/examples/category3'
components:
  schemas:
    CategoryItem:
      type: object
      required:
        - id
        - name
        - slug
        - createdDate
      properties:
        id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        name:
          type: string
          example: Category 1
        slug:
          type: string
          example: category-1
        description:
          type: string
          example: This is a sample category
        parent:
          type: string
          example: null
        createdDate:
          type: string
          format: date-time
          example: '2016-08-29T09:12:33.001Z'
  examples:
    category1:
      value:
        id: d290f1ee-6c54-4b01-90e6-d701748f0851
        name: Category 1
        slug: category-1
        description: This is the sample description for Category 1
        parent: null
        createdDate: '2016-08-29T09:12:33.001Z'
    category2:
      value:
        id: d290f1ee-6c54-4b01-90e6-d701748f0851
        name: Category 2
        slug: category-2
        description: This is the sample description for Category 2
        parent: null
        createdDate: '2016-08-29T09:12:33.001Z'
    category3:
      value:
        id: d290f1ee-6c54-4b01-90e6-d701748f0851
        name: Category 3
        slug: category-3
        description: This is the sample description for Category 3
        parent: d290f1ee-6c54-4b01-90e6-d701748f0851
        createdDate: '2016-08-29T09:12:33.001Z'
servers:
  - url: 'https://virtserver.swaggerhub.com/factly/test/1.0.0'

The response I am expecting is the following:

[{
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "Category 1",
    "slug": "category-1",
    "description": "This is the sample description for Category 1",
    "createdDate": "2016-08-29T09:12:33.001Z"
},
{
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "Category 2",
    "slug": "category-2",
    "description": "This is the sample description for Category 2",
    "createdDate": "2016-08-29T09:12:33.001Z"
},
{
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "Category 3",
    "slug": "category-3",
    "description": "This is the sample description for Category 3",
    "parent": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "createdDate": "2016-08-29T09:12:33.001Z"
}]

Thanks, Shashi

Can you clarify what you mean by "get all the three categories defined as a response"? Do you expect to mock to cycle through the category1, category2 and category3 responses sequentially? Or something else? — Helen, Nov 28 '18 at 10:09
Hi Helen, thanks for your response. I updated the question with the response object I am expecting when I query the API. Thanks. — Shashi Deshetti, Nov 28 '18 at 11:39
Similar questions about OpenAPI 2.0: [How to add an array example with multiple values in Swagger?](https://stackoverflow.com/q/46578110/113116), [Return an array of objects in SwaggerHub](https://stackoverflow.com/q/46167981/113116) — Helen, Nov 28 '18 at 14:08

Helen · Accepted Answer · 2018-11-28T22:28:01.417

So your response is an array of objects, and you want to specify the response example containing an array with multiple items.

There are several ways to specify examples for array responses, but in any case the example must be a complete example, that is you cannot $ref'erence parts of an example (such as the values of individual array items). In other words, the example value cannot be built from partial $refs.

You can put the example inside your array schema, alongside type: array:

          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryItem'
                example:
                  - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                    name: Category 1
                    slug: category-1
                    description: This is the sample description for Category 1
                    createdDate: '2016-08-29T09:12:33.001Z'
                  - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                    name: Category 2
                    slug: category-2
                    description: This is the sample description for Category 2
                    createdDate: '2016-08-29T09:12:33.001Z'
                  - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                    name: Category 3
                    slug: category-3
                    description: This is the sample description for Category 3
                    parent: d290f1ee-6c54-4b01-90e6-d701748f0851
                    createdDate: '2016-08-29T09:12:33.001Z'

Or add the example alongside the response schema:

          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryItem'
              example:
                - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                  name: Category 1
                  slug: category-1
                  description: This is the sample description for Category 1
                  createdDate: '2016-08-29T09:12:33.001Z'
                - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                  ...

Or if you want to specify a description for the example, use the examples keyword (plural) as shown below. (But examples are currently not displayed in Swagger UI.)

          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryItem'
              examples:
                categoryWithThreeItems:
                  summary: Example of a category with three items
                  value:
                    - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                      name: Category 1
                      slug: category-1
                      description: This is the sample description for Category 1
                      createdDate: '2016-08-29T09:12:33.001Z'
                    - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                      ...

or put the whole example to the components/example section and $ref it. Note again, we can $ref whole examples only but not parts of an example.

          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryItem'
              examples:
                categoryWithThreeItems:
                  $ref: '#/components/examples/categoryWithThreeItems'
components:
  examples:
    categoryWithThreeItems:
      summary: Example of a category with three items
      value:
        - id: d290f1ee-6c54-4b01-90e6-d701748f0851
          name: Category 1
          slug: category-1
          description: This is the sample description for Category 1
          createdDate: '2016-08-29T09:12:33.001Z'
        - id: d290f1ee-6c54-4b01-90e6-d701748f0851
          ...

Hi Helen, Thanks again for your detailed response. I am looking for a solution where the example is reusable. The reason I was using $ref: '#/components/examples/category1' is to reuse the category within other responses as well? — Shashi Deshetti, Nov 28 '18 at 22:16
I added an example of using `#/components/examples` to specify the array value. As for the `category1`, `category2`, etc. examples from your original question - you can use them as standalone examples (e.g. in resources that accept/return a single category), but it's not possible to build the array example by combining $ref'erenced examples. $refs are not resolved inside `example` and `examples..value`; the content of these keys is taken as is, as a literal example value. — Helen, Nov 28 '18 at 22:35

Swagger OAS3.0 Multiple responses in the same response code

1 Answers1