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.
Related
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
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'm using Swagger, one of the Open API tools to define an API.
For example, I have an object NameValue { propertyName: propertyValue}
How to let Sagger allow propertyValue could be integer, string, boolean.
NameValue:
type: "object"
required:
- "propertyName"
properties:
propertyName:
type: allow integer, string, boolean.
I have try
propertyName:
oneOf:
- type: "integer"
- type: "string"
- ypte: "boolean"
But it does not work. I have searched the google, but find nothing about this.
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.