Swagger OAS3.0 Multiple responses in the same response code - swagger

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

Answer 1

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
...