In short, here's fragment of OpenAPI specification:
# Consider an imaginary Internet Service Provider that needs to limit
# one or multiple customers in different ways: bandwidth (inbound, outbound), media type (text / music / video), volume (total traffic volume, for example, 5 GB).
# per specific website (a user can have different limit for YouTube and Amazon).
# You'll likely want to rename some of the attributes but
#that's not the point (this API is fake and that's the best example I came up with to reproduce the issue).
components:
schemas:
ProviderLimit:
type: object
properties:
name:
type: string
website_id:
type: string
users:
type: array
items:
type: string
description: List of user IDs
minItems: 1
bandwidth:
type: object
$ref: '#/components/schemas/BandwidthLimit'
volume:
type: object
$ref: '#/components/schemas/VolumeLimit'
media:
type: string
enum:
- TEXT
- MUSIC
- VIDEO
BandwidthLimit:
properties:
incoming_speed:
type: string
format: int64
outcoming_speed:
type: string
format: int64
VolumeLimit:
properties:
target:
type: string
format: int64
The question is which approach shall I take:
Merge all the possible limits (bandwith, volume, media), make them all optional, and agree to specify just one of them on the client.
Use oneOf.
# Example of using oneOf
components:
schemas:
ProviderLimit:
type: object
properties:
name:
type: string
website_id:
type: string
users:
type: array
items:
type: string
description: List of user IDs
minItems: 1
limit_type:
type: object
oneOf:
- $ref: '#/components/schemas/BandwidthLimit'
- $ref: '#/components/schemas/VolumeLimit'
- $ref: '#/components/schemas/MediaLimit'
discriminator:
propertyName: type # or something else
It looks like option #2 looks a little bit better but overall one could tell #1 option is somewhat reasonable (it's very simple and doesn't overcomplicate the API). Is there a strong argument to use #2 besides it just looks a little bit better (for example, there's a use case where using #1 might not lead to expected results)?
I have the following schemas defined in Open API:
components:
schemas:
ParentModel:
type: object
properties:
type:
type: string
enum: [value1, value2, value3]
ChildModel:
allOf:
- $ref: '#/components/schemas/FieldDefinition'
What I want is to specify a value for the type property of the ParentModel in the ChildModel, from the enum list. Something like:
ChildModel:
allOf:
- $ref: '#/components/schemas/FieldDefinition'
- type: object
properties:
type:
value: text
AnotherChildModel:
allOf:
- $ref: '#/components/schemas/FieldDefinition'
- type: object
properties:
type:
value: text
I know that I could define that type attribute in every model, but I would prefer to do it that way to show all the possible values. Any idea if this is possible at al?
Here the documentation explains how to define discriminators when an OpenAPI schema is dependent on the value of a property. In my own project, I have a schema that is dependent on the values of two properties, not just one. I wonder whether there is any way to model that in an OpenAPI file?
Let's say we have a list of requests with two required enum properties:
requestType: It could be either of these values:
New
Old
periodType: It could be either of these values:
Temporary
Permanent
The values of the rest of properties are somehow dependent on the values of these 2 fields. So there are 4 possible schemas which we want to discriminate them based on these 2 fields. One possible solution that came to my mind was to use a nested structure like this:
ListResponse:
type: array
items:
oneOf:
- $ref: '#/components/schemas/NewRequestResponse'
- $ref: '#/components/schemas/OldRequestResponse'
discriminator:
propertyName: requestType
mapping:
'New':
oneOf:
- $ref: '#/components/schemas/NewTemporaryRequestResponse'
- $ref: '#/components/schemas/NewPermanentRequestResponse'
discriminator:
propertyName: periodType
mapping:
'Temporary': '#/components/schemas/NewTemporaryRequestResponse'
'Permanent': '#/components/schemas/NewPermanentRequestResponse'
'Old':
oneOf:
- $ref: '#/components/schemas/OldTemporaryRequestResponse'
- $ref: '#/components/schemas/OldPermanentRequestResponse'
discriminator:
propertyName: periodType
mapping:
'Temporary': '#/components/schemas/OldTemporaryRequestResponse'
'Permanent': '#/components/schemas/OldPermanentRequestResponse'
uniqueItems: true
But seemingly this is not a valid schema. So, how could it be done?
The models.yaml file I have is:
baseStorePatch:
title: Store
type: object
required:
- scalePolicy
properties:
scalePolicy:
$ref: "#/definitions/scalePolicy"
StorePatch:
allOf:
- $ref: "#/definitions/baseStorePatch"
- type: object
properties:
However, when I use go-swagger to generate the clients, the output is:
type StorePatch struct {
ScalePolicy *StorePatchAO0ScalePolicy `json:"scalePolicy,omitempty"`
}
Why the go-swagger auto generate StorePatchAO0 as the prefix? And how to get rid of it?
I would like to post an array of strings like
[
"id1",
"id2"
]
to a Swagger based API. In my swagger file, I have those lines:
paths:
/some_url:
post:
parameters:
- name: ids
in: body
required: true
What is the correct way to specify the type of ids as an array of strings?
Update:
According to the specification, the following should work in my option:
parameters:
- in: body
description: xxx
required: true
schema:
type: array
items:
type: string
https://github.com/Yelp/swagger_spec_validator does not accept it and returns a long list of convoluted errors, which look like the code expects some $ref.
Your description of an array of string is correct, but the parameter definition misses the name property to be valid.
Here's a full working example:
swagger: "2.0"
info:
title: A dummy title
version: 1.0.0
paths:
/path:
post:
parameters:
- in: body
description: xxx
required: true
name: a name
schema:
type: array
items:
type: string
responses:
default:
description: OK
Try the online editor to check your OpenAPI (fka. Swagger) specs: http://editor.swagger.io/
I have created a swagger issue as the help provided by Arnaud, although is valid yaml, will give you NPE exceptions when trying to generate. You will need to provide an object like the following:
myDataItem:
type: object
description: A list of values
required:
- values
properties:
values:
type: array
items:
type: string
And then refer to it (in your post item etc):
schema:
$ref: "#/definitions/myDataItem"
For reference the github issue:
https://github.com/swagger-api/swagger-codegen/issues/6745
Note, the issue has been fixed in version 2.3.0 and higher, ideally you should upgrade to that version.
None of the answers worked for me. As it is stated in the following Baeldung article:
To better document the API and instruct the user, we can use the example label of how to insert values
So the full working example would be something like that:
swagger: "2.0"
info:
title: A dummy title
version: 1.0.0
paths:
/path:
post:
parameters:
- in: body
description: xxx
required: true
name: a name
schema:
type: array
items:
type: string
example: ["str1", "str2", "str3"]
responses:
default:
description: OK
You can check how the Example Value is now better informed in the Swagger editor.
For Array containing Object as it's content, definition for Object can be also expressed using definitions & $ref.
Example:
schema:
type: array
items:
$ref: '#/definitions/ObjectSchemaDefinition'
definitions:
ObjectSchemaDefinition:
type: string
The answer with the most votes got me in the right direction. I just needed an example of an array of objects where each one of them had a property which was an array of strings with more than one value in the strings array. Thanks to the documentation I got it working like this:
MyObject:
type: object
properties:
body:
type: array
items:
type: object
properties:
type:
type: string
values:
type: array
items:
type: string
example:
- type: "firstElement"
values: ["Active", "Inactive"]
- type: "SecondElement"
values: ["Active", "Inactive"]
One thing to keep in mind is that indentation is of paramount importance to swagger. If you don't indent things well, swagger will give you strange error messages.