Swagger: schema definition for two different objects - json

Question

I have to create an API that can return JSON object in two different formats based on the input parameter. Suppose if we pass "report=monthly" in query string the output will be like:
[{
"Month": "Jan",
"Details": [{
"userId": 12345,
"userName": "ABC"
}]
}, {
"Month": "Feb",
"Details": [{
"userId": 12346,
"userName": "ABD"
}]
}]
If the above parameter is not passed the output will be like:
{
"Details": [{
"userId": 12345,
"userName": "ABC"
}, {
"userId": 12346,
"userName": "ABD"
}]
}
How can I define schema for a single API to return JSON in the above formats? I can not create 2 endpoints.

Answer 1

The easier way is to define Month as an optional property.
paths:
/report:
parameters:
...
get:
responses:
200:
description: OK
schema:
type: array
items:
$ref: '#/definitions/ReportEntry'
definitions:
ReportEntry:
type: object
properties:
Month:
type: string
example: Jan
Details:
type: array
items:
$ref: '#/definitions/UserInfo'
required:
- Details # <---- "Details" is required, "Month" is optional
UserInfo:
type: object
properties:
userId:
type: integer
example: 12345
userName:
type: string
example: ABC
required:
- userId
- userName