I'm using Swagger OpenApi 3.0.3 and want to use an array field with objects in it. My field definition is the following:
* - name: filter_query
* in: query
* schema:
* type: array
* items:
* type: object
* properties:
* value:
* type: string
* field_id:
* type: string
* description: Filter
If y add two objects to the array a get an array but if I just send one object I receive an object. Am I missing something?!
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
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