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'
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
The doc says we can use oneOf under array for mixed types and arrays
type: array
items:
oneOf:
- type: integer
- type: string
or
type: array
items:
oneOf:
- $ref: "#/components/object1"
- $ref: "#/components/object2"
I need to have an array with a mix of type and ref like so:
type: array
items:
oneOf:
- type: integer
- $ref: "#/components/object2"
The documentation doesn't say anything about this, and I can't seem to make the validation work. Is it not supported? Or am I doing something wrong?
I'm writing an OpenAPI definition for the oldResource field which can be an object (basically, a hashmap) or a byte array. Like below -
{"oldResource" : <object(hashmap) or byte array>}
How can I define such a field in OpenAPI?
I have tried the following
oldResource:
description: Old Resource map/byte array
type: object
anyOf:
- type: object
- type: array
items:
type: byte
But, this gives me an error.
How do I fix this?
You have to use type string and the format byte:
String Formats
oldResource:
description: Old Resource map/byte array
type: object
anyOf:
- type: object
- type: array
items:
type: string
format: byte
Following the example of an OpenAPI 3 definition:
components:
schemas:
Foo:
properties:
string:
type: string
enumField:
type: string
enum: ['VALUE_1', 'VALUE_2']
Bar:
properties:
enumField:
type: string
enum: ['VALUE_1', 'VALUE_2']
Is there a way to reuse enumField or do I have to specify it every time I use it?
I don't know if is possible to reference a single property, but you can do it with schemas, and by spliting it.
Here is a basic structure sample of what can you do:
SchemaBase:
type: object
properties:
foo:
type: string
SchemaFull:
allOf:
- $ref: '#/components/schemas/SchemaBase'
- type: object
properties:
bar:
type: string
In your case could be something like this:
components:
schemas:
EnumField:
properties:
enumField:
type: string
enum: ['VALUE_1', 'VALUE_2']
Foo:
allOf:
- $ref: '#/components/schemas/EnumField'
- properties:
string:
type: string
Bar:
allOf:
- $ref: '#/components/schemas/EnumField'
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.