I have an input in the below format:
{"value" : {"codes": ["123","234"]} }
I have a swagger document as below but it does not yield the above result
/v1/search:
post:
summary: Get values
description: Get values
parameters:
- name: value
in: body
schema:
properties:
value:
type: array
items:
$ref: "#/definitions/Values"
definitions:
Values:
type: object
properties:
codes:
type: string
Any leads would be appreciated.
Try this. I used Value and Codes as schema names, but feel free to change them as you see fit.
- name: value
in: body
schema:
$ref: '#/definitions/Value'
definitions:
Value:
type: object
properties:
value:
$ref: '#/definitions/Codes'
Codes:
type: object
properties:
codes:
type: array
items:
type: string
Related
I have the following API definition in SwaggerHub:
swagger: '2.0'
info:
description: defaultDescription
version: '0.1'
title: defaultTitle
host: swapi.co
paths:
/api/people:
get:
produces:
- application/json
parameters:
- name: search
in: query
required: false
type: string
x-example: luke
responses:
'200':
description: Definition generated from Swagger Inspector
schema:
$ref: '#/definitions/Model0'
responseSchema:
$ref: '#/definitions/Model0'
definitions:
Results:
properties:
name:
type: string
height:
type: string
mass:
type: string
hair_color:
type: string
skin_color:
type: string
eye_color:
type: string
birth_year:
type: string
gender:
type: string
homeworld:
type: string
films:
type: array
items:
type: string
species:
type: array
items:
type: string
vehicles:
type: array
items:
type: string
starships:
type: array
items:
type: string
created:
type: string
edited:
type: string
url:
type: string
Model0:
properties:
count:
type: integer
format: int32
next:
type: object
previous:
type: object
results:
type: array
items:
$ref: '#/definitions/Results'
I cannot make this basic GET command to bring back the data I'm seeking. It only returns this:
TypeError: Failed to fetch
I'm unsure if it's a syntax issue, or possibly spacing, but I'm also getting an error for line 19 that reads:
should NOT have additional properties
additionalProperty: responseSchema, description, schema
Any ideas what is wrong?
https://swapi.co seems to be HTTPS-only, so you need to add
schemes:
- https
to you API definition to specify the protocol for requests.
but I'm also getting an error for line 19 that reads: "should NOT have additional properties additionalProperty: responseSchema, description, schema".
Remove these lines:
responseSchema:
$ref: '#/definitions/Model0'
There's no responseSchema keyword in OpenAPI.
I have a data model definition in OpenAPI 3.0, using SwaggerHub to display the UI. I want one of the properties of a model to be related, which is an array of properties of the same model.
Foo:
properties:
title:
type: string
related:
type: array
items:
$ref: '#/components/schemas/Foo'
The parser doesn't seem to like this - the UI shows the related property as an empty array. Is this kind of self-reference possible in OpenAPI 3.0?
Your definition is correct, it's just Swagger UI currently does not render circular-referenced definitions properly. See issue #3325 for details.
What you can do is add a model example, and Swagger UI will display this example instead of trying to generate an example from the definition.
Foo:
type: object
properties:
title:
type: string
related:
type: array
items:
$ref: '#/components/schemas/Foo'
example: # <-------
title: foo
related:
- title: bar
- title: baz
related:
- title: qux
Alternatively, you can add an example just for the related array:
Foo:
type: object
properties:
title:
type: string
related:
type: array
items:
$ref: '#/components/schemas/Foo'
example: # <--- Make sure "example" is on the same level as "type: array"
- title: bar
- title: baz
related:
- title: qux
I got tired of this pesky situation, so I went with no example at all and chose to get rid of the items property, add a description element and use an empty array instead:
Foo:
type: object
properties:
title:
type: string
related:
type: array
description: Array of Foo elements
example: []
You can achieve that by a proxy model:
...
_MessageProxy:
description: Message
type: object
required:
- id
- user
- body
- publishedAt
properties:
id:
title: Message id
type: string
readOnly: true
example: '595f4acf828b0b766ad11290'
user:
$ref: '#/components/schemas/User'
Message:
allOf:
- $ref: '#/components/schemas/_MessageProxy'
- type: object
properties:
parent:
title: Parent
readOnly: true
allOf:
- $ref: '#/components/schemas/_MessageProxy'
...
Using a dummy model and cross reference:
Foo:
properties:
title:
type: string
related:
type: array
items:
$ref: '#/components/schemas/_Foo'
_Foo:
properties:
title:
type: string
related:
type: array
items:
$ref: '#/components/schemas/Foo'
VehicleBaseAttributes:
type: object
properties:
id:
type: integer
format: int64
model:
type: string
doors:
type: integer
VehicleExtendedAttributes:
type: object
properties:
$ref: '#/components/schemas/VehicleBaseAttributes'
pricehistory:
type: array
items:
title: PriceHistory
type: object
properties:
priceWOT:
type: number
taxes:
type: number
additionalCosts:
type: number
price:
type: number
createdByUserId:
type: string
createdDate:
type: string
dealerHistory:
type: array
items:
title: DealerHistory
type: object
properties:
name:
type: string
phone:
type: string
createdByUserId:
type: string
createdDate:
type: string
In the above example I intended to have a basic set of attributes defined, then offer an extended version that used the base version.
Obviously in the VehicleExtendedAttributes I don't want to nest the VehicleBaseAttributes in a separate attribute, instead for them to be added to the top level, resulting in an output of something like:
type: object
properties:
id:
type: integer
format: int64
model:
type: string
doors:
type: integer
pricehistory:
type: array
items:
title: PriceHistory
type: object
properties:
priceWOT:
type: number
taxes:
type: number
additionalCosts:
type: number
price:
type: number
createdByUserId:
type: string
createdDate:
type: string
dealerHistory:
type: array
items:
title: DealerHistory
type: object
properties:
name:
type: string
phone:
type: string
createdByUserId:
type: string
createdDate:
type: string
The problem is this results in an error:
Schema error at components.schemas['VehicleExtendedAttributes']
should have required property '$ref'
missingProperty: $ref
Jump to line 342
Schema error at components.schemas['VehicleExtendedAttributes']
should match exactly one schema in oneOf
Jump to line 342
Schema error at components.schemas['VehicleExtendedAttributes'].properties['$ref']
should be object
Jump to line 345
You need allOf to do model composition. The value of allOf is a list of subschemas ($referenced or inline) that together compose a single schema.
VehicleExtendedAttributes:
allOf:
- $ref: '#/components/schemas/VehicleBaseAttributes'
- type: object
properties:
pricehistory:
type: array
...
dealerHistory:
type: array
...
Further info:
Swagger Inheritance and Composition here on Stack Overflow
Composition and Inheritance (Polymorphism) section of the OpenAPI 3.0 Specification
Model Composition, Inheritance and Polymorphism
oneOf, anyOf, allOf, not
Code below:
definitions:
Result:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
FindUID:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
data:
type: object
properties:
uid:
type: integer
format: int64
FindUsername:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
data:
type: object
properties:
username:
type: string
As you can see, the first part of FindUID and FindUsername is the same as Result. How to replace those duplicate code with Result?
You can compose definitions using allOf, here's a full example where Result is used in FindUID and FindUsername:
swagger: '2.0'
info:
description: Example API Description
title: Example Title
version: 1.0.0
paths: {}
definitions:
Result:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
FindUID:
allOf:
- $ref: "#/definitions/Result"
- type: object
properties:
data:
type: object
properties:
uid:
type: integer
format: int64
FindUsername:
allOf:
- $ref: "#/definitions/Result"
- type: object
properties:
data:
type: object
properties:
username:
type: string
More about this here: https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-4-advanced-data-modeling/ (disclosure: I wrote this tutorial)
In the following Swagger definition, I need the parameter labelValue to be of type LabelValueObject, so that it will be validated and correctly deserialized. However, I can't figure out the syntax! How can that be done?
swagger: "2.0"
paths:
/competition:
post:
parameters:
- name: labelValue
in: formData
type: array
items:
type: string ### this has to be a LabelValueObject ###
responses:
default:
description: Error
schema:
$ref: "#/definitions/AnyResponse"
definitions:
AnyResponse:
properties:
any:
type: string
LabelValueObject:
properties:
label:
type: string
value:
type: string
required:
- label
- value
The only way to pass an object as a parameter is to put it in the body (in: body) and then define this object in schema (inline definition or reference to an predefined object with $ref). Here's a full example:
swagger: "2.0"
info:
title: A dummy title
version: 1.0.0
paths:
/competition:
post:
parameters:
- name: labelValue
in: body
schema:
$ref: '#/definitions/LabelValueObject'
responses:
default:
description: Error
schema:
$ref: "#/definitions/AnyResponse"
definitions:
AnyResponse:
properties:
any:
type: string
LabelValueObject:
properties:
label:
type: string
value:
type: string
required:
- label
- value