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