I have several levels of nested objects in my response and I cannot change these. How can I represent these in a Swagger doc definition?
{
name.response: {
name.result: {
name.row: [
{
name.first: "John",
name.last: "Doe",
}
]
}
}
}
Here is what I have right now:
person:
type: object
properties:
name.first:
type:string
name.last
type.string
name.result:
type: object
properties:
name.row:
type: array
items:
$ref: '#/definitions/person'
name.response:
type: object
properties:
name.result:
type: object
description: Result
I don't think this is right because the Swagger Editor is warning me that the name.result definition is not being used.
Nevermind!
I figured it out:
name.response:
type: object
properties:
name.result:
type: object
description: Result
$ref: '#/definitions/name.result'
I had tried this already, but the warning that name.result wasn't being used was still there...
But then I refreshed the Swagger Editor and the warning went away.
Related
I am using Swagger OpenAPI Specification tool. I have a string array property in one of the definitions as follows:
cities:
type: array
items:
type: string
example: "Pune"
My API produces JSON result, so Swagger UI displays the following example for the response:
{
"cities": [
"Pune"
]
}
How can I add multiple example values for the cities array? Expecting the result as:
{
"cities": [
"Pune",
"Mumbai",
"Bangaluru"
]
}
Tried comma-separated strings in the example key like below:
cities:
type: array
items:
type: string
example: "Pune", "Mumbai", "Bangaluru"
But the Swagger Editor shows an error, "Bad indentation".
Is there any way to specify multiple values in the example key?
Update
User Helen below has given the correct answer. I had an indentation problem hence there were nested arrays (2d arrays)
Correct way:
cities:
type: array
items:
type: string
example:
- Pune
- Mumbai
My way (which was wrong)
cities:
type: array
items:
type: string
example:
- Pune
- Mumbai
Look for the indentation of the example key in the above two cases which makes the difference, its YAML indentation matters.
To display an array example with multiple items, add the example on the array level instead of item level:
cities:
type: array
items:
type: string
example:
- Pune
- Mumbai
- Bangaluru
# or
# example: [Pune, Mumbai, Bangaluru]
In case of array of objects, the example would look like this:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
example:
- id: 1
name: Prashant
- id: 2
name: Helen
paths:
/products_1:
get:
responses:
'200':
description: "XYZ"
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/pro'
example:
- name : "Laptop"
dist : "HP LAPTOP"
- name : "Mobile"
dist : "Apple Mobile"
components:
schemas:
pro:
type: object
properties:
prodName:
type: string
example: "Laptop"
prodDesc:
type: string
example: "Produc Description"
For openapi version - 3.0.0+
major:
type: array
items:
type: string
enum:
- Accounting
- Business Contacts
- Economy
- Finance
- Graphic Design
- International Business Administration
- International Relations
- Law
- Marketing
- others
- Political Science
- Statistics
I'm new to openAPI 3.0 specs and wanted to know if one can override the key status to somestatus?
Response:
type: object
properties:
status: # want to override this key
type: number
format: int32
timestamp:
type: string
format: date-time
ApiResponse:
allOf:
- $ref: '#/components/schemas/Response'
- type: object
properties:
message:
type: string
format: string
The Response has a field status so will ApiResponse as it extends it. Now can I override the key value status to something else in ApiResponse.
Our Schema is pretty evolved so just came up with this generic example. I think it's not possible but I still wanted to ask it out.
How can I best describe a generic response type which includes the real data type in OpenAPI 3.
Simplified example:
ApiResponse:
data: object
error: string
But the /users endpoint should give:
ApiResponse<List<User>>
So that basically is:
ApiResponse:
data: List<User>
error: string
It looks like this is not possible at the moment, but just want to make sure.
I guess the best way to do this now is to make named responses for every call and use allOf to refer to ApiResponse and implemenent data: specific value.
I search for generic types much time, but there is no way to define a generic type in OpenAPI3. The simplest way is using allOf and $ref at the same time. Suppose there is a list schema as follow:
List:
type: object
properties:
page_number:
type: integer
page_count:
type: integer
And the book schema is
Book:
type: object
properties:
title:
type: string
summary:
type: string
To return a list, the path is:
/api/v1/books:
get:
responses:
default:
description: description text
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/List'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Book'
Thie result is
{
"page_number": 1,
"page_count": 10,
"items": [{
"title": "title",
"description": ""
},
... ]
}
Actually, this is a list of books. As you can see, you add main attributes of the list to the result and list item type at the same time. You can repeat this pattern for others too:
/api/v1/authors:
get:
responses:
default:
description: description text
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/List'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Author'
Well, you can use type object with additionalProperties with true value to get free form objects.
I want to write a API that would respond with an array. My OpenAPI description looks like this:
definitions:
DeviceArray:
type: array
items:
type: string
example:
- {"DeviceID": 103609131103,"NetworkName": "nzp-20007-gnd-rt-01","RelativeName": "NZP-20007-GND-RT-01.PST.SYTECNMS.NET","Type": null}
- {"DeviceID": 105621398103,"NetworkName": "nzp-20007-gnd-as-01","RelativeName": "NZP-20007-GND-AS-01.PST.SYTECNMS.NET","Type": null}
- {"DeviceID": 122403148102,"NetworkName": null,"RelativeName": "BEAS/U_NTU_001","Type": "NTU"}
- {"DeviceID": 165002297102,"NetworkName": null,"RelativeName": "BEAS/G_HSNS SDP_001","Type": "Alcatel MSAP"}
- {"DeviceID": 165002320102,"NetworkName": "10.6.194.126","RelativeName": "BEAS/G_ONEA1424X_001","Type": "OneAccess IAD/Router"}
- {"DeviceID": 160885080102,"NetworkName": null,"RelativeName": "BEAS/U_CISCO_1921_001","Type": "Cisco Packet Switch"}
But the response I get is:
[
""
]
How do I solve this problem?
This is not type: string obviously, you need to set the type to type: object and either define it directly:
type: array
items:
type: object
properties:
DeviceID:
type: string
NetWorkName:
type: string
RelativeName:
type: string
or reference an object if you have already defined it:
type: array
items:
$ref: '#/yourObjectReference'
I am looking to represent the following JSON Object in OpenAPI:
{
"name": "Bob",
"age": 4,
...
}
The number of properties and the property names are not fully predetermined, so I look to use additionalProperties. However, I'm not too certain how it would be represented through OpenAPI/Swagger 2.0. I tried this:
Person:
type: object
additionalProperties:
type:
- int
- string
or the JSON equivalent:
{
"Person": {
"type": "object",
"additionalProperties": {
"type": ["int", "string"]
}
}
}
but that didn't quite work. Is there any way to keep the structure of the JSON Object I want to represent, for specifically strings and integers, and not arbitrary object types?
OpenAPI 3.1
In OpenAPI 3.1, the type keyword can take a list of types:
Person:
type: object
additionalProperties:
type: [string, integer]
OpenAPI 3.x
OpenAPI 3.0+ supports oneOf so you can use:
Person:
type: object
additionalProperties:
oneOf:
- type: string
- type: integer
OpenAPI 2.0
OpenAPI 2.0 does not support multi-type values. The most you can do is use the typeless schema, which means the additional properties can be anything - strings, numbers, booleans, and so on - but you can't specify the exact types.
Person:
type: object
additionalProperties: {}
This is equivalent to:
Person:
type: object