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?
Related
In my service schema I've got a single object that has two choices of properties. Meaning;
Object A needs: property 1 or 2, and property 3 or 4.
To realise this in OAS I'm using an object with an allOf property, which contains two items containing a oneOf property. I don't see a reason why this construction would be illegal. However, when using the swagger editor (https://editor.swagger.io/) and the Swagger Viewer extension in VSCode, it merges the two oneOf properties into a single one, effectively instructing the user to either include property 1, 2, 3 or 4.
One other way to achieve the same is to define a schema for every combination of choice 1 and 2, but this gets very tedious as the amount of options expands (effectively multiplying for every combination of the two choices).
Is my interpretation of the way this should work correct? If not, how can I achieve my goal without the spec becoming too verbose? If yes, I take it this is an issue in both tools I'm using, in that case I'll raise an issue in the respective issue trackers.
Example OAS spec:
openapi: 3.0.3
info:
description: Test API
version: 0.1.0
title: Test API
paths:
/test:
post:
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TestComplexObject'
responses:
'200':
description: OK
components:
schemas:
TestComplexObject:
type: object
allOf:
- type: object
properties:
defaultString:
type: string
- oneOf:
- $ref: '#/components/schemas/TestStr1'
- $ref: '#/components/schemas/TestStr2'
- oneOf:
- $ref: '#/components/schemas/TestStr3'
- $ref: '#/components/schemas/TestStr4'
TestStr1:
type: object
properties:
testString1:
type: string
required: [testString1]
TestStr2:
type: object
properties:
testString2:
type: string
required: [testString2]
TestStr3:
type: object
properties:
testString3:
type: string
required: [testString3]
TestStr4:
type: object
properties:
testString4:
type: string
required: [testString4]
Is it some how possible to specify constants/enums for properties inside referenced complex properties in OpenAPI?
I know for a simple string property I can specify some enum constants which I expect/ allow (as you can see in the example below at property sortOrder.
As you can see in this example I define the TestSearchModel with the property orderBy which is of a referenced type SortModel. SortModel is actually defined in another file of a framework (PS: I have access and the permission to change that framework for my needs). In this SortModel there is the property sortFieldName. I wish I could specify in TestSearchModel that I only allow e.g. ATTR_ONE. Is that possible?
Maybe you can image my use case. I would like to define a search operation which expects an input of type TestSearchModel. With this input it should be possible to define a column/property by with the sorting of the results found should be done.
openapi.yaml:
TestSearchModel:
type: object
properties:
orderBy:
$ref: "#/SortModel"
enum: // allowed values of property sortFieldName in SortModel
- ATTR_ONE
- ATTR_TWO
SortModel:
type: object
properties:
sortFieldName:
type: string
sortOrder:
type: string
enum:
- ASC
- DESC
This should be valid:
{
"orderBy": {
"sortFieldName": "ATTR_ONE",
"sortOrder": "ASC"
}
}
This should end up in an error, because 'ATTR_THREE' is not defined above in the allowed values:
"sortModel": {
"sortFieldName": "ATTR_THREE",
"sortOrder": "ASC"
}
I actually guess that with OpenAPI Spec this kind of specification is not possible. However may be you can provide some recommendations how to handle that.
I tried out the example above. OpenAPI generates the model classes without any error but (some kind of expected) without considering the limitation of the allowed strings for 'order by' property. I wish that an enum would be generated for ATTR_ONE and ATTR_TWO.
It's possible. You'll need to add an extra schema alongside the $ref that defines a property with the same name on the same nesting level.
If you use OpenAPI 3.0.x or 2.0, make sure to wrap the $ref into allOf:
TestSearchModel:
type: object
properties:
orderBy:
allOf:
- $ref: "#/SortModel" # or "#/components/schemas/SortModel" or whatever the correct $ref path is
- properties: # <---
sortFieldName: # <---
enum:
- ATTR_ONE
- ATTR_TWO
SortModel:
type: object
properties:
sortFieldName:
type: string
sortOrder:
type: string
enum:
- ASC
- DESC
In OpenAPI 3.1, you can add keywords directly alongside the $ref:
# openapi: 3.1.0
TestSearchModel:
type: object
properties:
orderBy:
$ref: "#/SortModel" # or "#/components/schemas/SortModel" or whatever the correct $ref path is
properties: # <---
sortFieldName: # <---
enum:
- ATTR_ONE
- ATTR_TWO
The problem with your schema above is that openapi won't read anything after the $ref field. So, the enum value you have placed there is ignored. You can move the enum to your SortModel and it will be available:
TestSearchModel:
type: object
properties:
orderBy:
$ref: "#/SortModel"
SortModel:
type: object
properties:
sortFieldName:
type: string
enum:
- ATTR_ONE
- ATTR_TWO
sortOrder:
type: string
enum:
- ASC
- DESC
If you are trying to reuse the enum, you can do this via a reference, like this
TestSearchModel:
type: object
properties:
orderBy:
$ref: "#/SortFields"
SortModel:
type: object
properties:
sortFieldName:
$ref: "#/SortFields"
sortOrder:
$ref: "#/SortOrderTypes"
SortOrderTypes:
type: string
enum:
- ASC
- DESC
SortFields:
type: string
enum:
- ATTR_ONE
- ATTR_TWO
I described my controller using Swagger but when I tried to extract .yaml description of controller, as response of endpoints I found list of objects. How to make Swagger describe those list as list of particular objects such as list of cars, list of houses, list of animals, etc. and then to describe what particular object like car, house or animal is.
My case is:
/dummy_endpoint:
get:
tags:
- foo-controller
summary: Get foo list
description: Send GET request to obtain foo list
operationId: findAllFooUsingGET
produces:
- application/json
responses:
'200':
description: Foo list obtained successfully
schema:
type: array
items:
type: object
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
What I want to get:
/dummy_endpoint:
get:
tags:
- foo-controller
summary: Get foo list
description: Send GET request to obtain foo list
operationId: findAllFooUsingGET
produces:
- application/json
responses:
'200':
description: Foo list obtained successfully
schema:
type: array
items:
type: Foo
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
definitions:
Foo:
type: object
properties:
id:
type: integer
format: int32
name:
type: String
I assume OpenAPI version 2.0 (based on the syntax in example). If you're using 3.0, let me know.
What you are looking for is ref. Check-in Swagger specification in section Input and Output Models and here in section Array and Multi-Value Parameters about arrays.
For example:
...
responses:
'200':
description: Foo list obtained successfully
schema:
type: array
items:
$ref: "#/definitions/Foo"
...
definitions:
Foo:
type: object
properties:
...
Thing that solved my problem was the usage of responseContainer property from #ResponseApi annotation, where I put type of response container like List, Array etc. and putting into response property type of objects that are stored into container.
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?
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.