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
Related
I am trying to add an array in my swagger 2.0 but I keep getting the following error:
Structural error at definitions.testPOST
should NOT have additional properties
additionalProperty: testRequests
I've checked the swagger documentation but I don't know what I am doing wrong. I could delete 'testRequests' but I need it.
The code is as follows:
swagger: '2.0'
info:
version: v1
title: testAPI
security:
- default: []
paths:
/testPOST:
post:
summary: test
description: test
parameters:
- in: body
name: Payload
description: test
required: true
schema:
$ref: '#/definitions/testPOST'
responses:
'201':
description: Success
schema:
type: object
properties:
status:
type: string
description: HTTP statuscode
title:
type: string
description: Success
detail:
type: string
description: Empty
'401':
description: No access
schema:
type: object
properties:
status:
type: string
description: HTTP statuscode
title:
type: string
description: Message invalid
detail:
type: string
description: Error message
'500':
description: Server error
security:
- default:
- testRequest
x-auth-type: Application & Application User
x-throttling-tier: Unlimited
x-wso2-application-security:
security-types:
- oauth2
optional: false
x-auth-type: Application & Application User
x-throttling-tier: Unlimited
securityDefinitions:
default:
type: oauth2
authorizationUrl: 'https://test.com'
flow: implicit
scopes:
testRequest: Scope
x-scopes-bindings:
testRequest: 'testRequest,admin'
definitions:
testPOST:
testRequests:
type: array
items:
type: object
properties:
sourceUrl:
type: string
example: 'http://example.com/test/1202112'
description: The reference url.
default: 'null'
inboundReferenceNumber:
type: string
example: '1234567890'
description: The request identifier.
default: 'null'
Can somebody please point out what I am doing wrong? Thanks in advance!
If the request body is supposed to be just an array of objects
[
{"sourceUrl": ...},
{"sourceUrl": ...},
...
]
then the definition should be:
definitions:
testPOST: # Remove the "testRequests:" line from here
type: array
items:
..
If the request body is supposed to be an object with the testRequests property whose value is an array
{
"testRequests": [
{"sourceUrl": ...},
{"sourceUrl": ...},
...
]
}
then the definition should be:
definitions:
testPOST:
type: object
properties:
testRequests:
type: array
items:
type: object
properties:
sourceUrl:
...
inboundReferenceNumber:
...
In my Swagger documentation, I have to use same pattern multiple time. Currently, it is placed duplicated.
One thing I improved is that making common parameter (by declaring it inside components). But couldn't find anything to avoid this duplicate pattern between parameters and schemas.
Is there any way, I can use declare this pattern once and re-use it wherever it's needed?
My Swagger looks something like:
openapi: 3.0.3
info:
title: My System
description: Self contained system
version: 1.0.0
servers:
- url: /a/{aId}/
description: Contains the partition
security:
- bearerAuth: []
paths:
"/x/{xId}/y/{yId}/z/{zId}":
get:
x-horizon-permission: "geo.floorplan.read"
tags:
- myTag
operationId: getValue
description: Get Value
parameters:
- name: xId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: yId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: zId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
responses:
"200":
description: OK
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Response'
patch:
tags:
- myTag
operationId: Update
description: Update Data
parameters:
- name: xId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: yId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: zId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Request'
responses:
"200":
description: OK
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Response'
components:
schemas:
Request:
type: object
properties:
data:
type: object
properties:
type:
type: string
id:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
Response:
type: object
properties:
links:
type: object
properties:
self:
type: string
data:
$ref: '#/components/schemas/Data'
Data:
type: object
properties:
type:
type: string
id:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
GeometryError:
type: object
required:
- code
- status
- title
properties:
id:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
status:
type: string
example: 400
title:
type: string
detail:
type: string
meta:
type: object
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
Define a schema with this pattern:
components:
schema:
UUID:
type: string
format: uuid # for tools/codegens that have built-in support for UUIDs
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
Then you can reference this schema from other schemas and parameter definitions:
parameters:
- name: xId
in: path
required: true
schema:
$ref: '#/components/schemas/UUID' # <-----
- name: yId
in: path
required: true
schema:
$ref: '#/components/schemas/UUID' # <-----
...
schemas:
Request:
type: object
properties:
data:
type: object
properties:
type:
type: string
id:
$ref: '#/components/schemas/UUID' # <-----
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.
In YAML file I have this:
parameters:
- name: body
in: body
required: true
description: Body of the request.
schema:
$ref: '#/definitions/MinimalProgresstrailEntry'
and it's rendered to this:
:
it doesn't render the reference for the body. It works fine for the responses but not for parameters.
reference definitions:
MinimalProgresstrailEntry:
type: object
properties:
memoText:
type: string
type:
type: string
enum:
- memo
- attachment
- link
Following swagger file works on swagger-editor :
swagger: '2.0'
info:
version: "0.0.0"
title: title
paths:
/persons:
get:
description: test
parameters:
- name: body
in: body
required: true
description: Body of the request.
schema:
$ref: '#/definitions/MinimalProgresstrailEntry'
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/MinimalProgresstrailEntry'
definitions:
MinimalProgresstrailEntry:
type: object
properties:
memoText:
type: string
type:
type: string
enum:
- memo
- attachment
- link
Working on writing an API spec for my service with swagger. I'm using a model definition ('#/definitions/prototype') as the body parameter of both the POST /prototypes and PATCH /prototypes/:id routes.
How do you specify that the PATCH route only accepts a subset of the properties in the body of the request that the POST route does? For example, I want the PATCH /instances/:id route to only allow modification of the mobileDeviceId prototypes property.
swagger: "2.0"
info:
title: ""
description: ""
version: "1.0.0"
host: foo.example.com
schemes:
- https
basePath: /v1
produces:
- application/json
consumes:
- application/json
paths:
/prototypes:
post:
summary: Create new prototype
parameters:
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
201:
description: Success
schema:
$ref: "#/definitions/SuccessCreated"
403:
description: Prototype limit exceeded error
schema:
$ref: "#/definitions/Error"
default:
description: Unexpected error
schema:
$ref: "#/definitions/Error"
/prototypes/{id}:
patch:
summary: Update an existing prototype's properties
parameters:
- name: id
in: path
type: number
description: ID property of a prototype
required: true
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
200:
description: Success
definitions:
Prototype:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
mobileDeviceId:
type: number
SuccessCreated:
type: object
description: Returned as response to successful resource create request
properties:
code:
type: number
default: 201
message:
type: string
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
fields:
type: string
Swagger uses json-schema: http://json-schema.org
$refs provide you w/ a way to repeat existing json-schema at a new path.
Notice that you are using a $ref for patch/parameters/-name:prototype/schema.
You can create a new definition just for patch in the definitions section and reference it instead
swagger: "2.0"
info:
title: ""
description: ""
version: "1.0.0"
host: foo.example.com
schemes:
- https
basePath: /v1
produces:
- application/json
consumes:
- application/json
paths:
/prototypes:
post:
summary: Create new prototype
parameters:
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
201:
description: Success
schema:
$ref: "#/definitions/SuccessCreated"
403:
description: Prototype limit exceeded error
schema:
$ref: "#/definitions/Error"
default:
description: Unexpected error
schema:
$ref: "#/definitions/Error"
/prototypes/{id}:
patch:
summary: Update an existing prototype's properties
parameters:
- name: id
in: path
type: number
description: ID property of a prototype
required: true
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/PatchPrototype"
responses:
200:
description: Success
definitions:
Prototype:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
mobileDeviceId:
type: number
PatchPrototype:
type: object
properties:
mobileDeviceId:
type: number
SuccessCreated:
type: object
description: Returned as response to successful resource create request
properties:
code:
type: number
default: 201
message:
type: string
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
fields:
type: string