I've been searching fruitlessly on how to swagger spec a POST body with a list inside of it. How do I do it? Here's what I have:
/groups:
post:
summary: Creates a group
parameters:
- name: body
in: body
schema:
properties:
name:
type: string
description:
type: string
groupType:
type: string
enum: [ "open", "closed", "secret" ]
users:
type: string list # <--------- a list of strings
responses:
201:
description: Group created
default:
description: Group creation failed
For property being an array of string, please refer to https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml#L660 as an example:
photoUrls:
type: array
items:
type: string
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:
...
I am new to Open API specification ( ia m using 3.0). I am playing with swagger Editor online tool and I am getting a weird error of:
"should NOT have additional properties
additionalProperty: Data1, Data2"
Here is sample of YAML file I am working with:
paths:
/api/assignment:
post:
tags:
- Assignment
summary: "Endpoint to create Resources in system"
description: "This endpoint will create blah blah"
operationId: CreateResource
parameters:
- name: assignment
in: body
description: "This is an object to be sent"
required: true
schema:
type: object
properties:
Ganesh:
type: integer
Test:
type: string
RefClaim:
Data1:
FirstName:
type: string
LastName:
type: string
Data2:
FirstName2:
type: string
LastName2:
type: string
I have seen all questions asked and tried with those but I could not get answer.
Note: I am using Open Api specification 3.0.1
There are a few issues:
1) in: body parameters are an OpenAPI 2.0 thing. OpenAPI 3.0 uses requestBody instead.
2) Nested objects also need the type: object and properties keywords.
The correct version is:
paths:
/api/assignment:
post:
tags:
- Assignment
summary: "Endpoint to create Resources in system"
description: "This endpoint will create blah blah"
operationId: CreateResource
requestBody: # <-----------
required: true
content:
application/json:
schema:
type: object
properties:
Ganesh:
type: integer
Test:
type: string
RefClaim:
type: object # <-----------
properties: # <-----------
Data1:
type: object # <-----------
properties: # <-----------
FirstName:
type: string
LastName:
type: string
Data2:
type: object # <-----------
properties: # <-----------
FirstName2:
type: string
LastName2:
type: string
I am defining an API specification in SwaggerHub using OpenAPI 2.0. The /contacts request returns an array of contacts. The definition is below:
/contacts:
get:
tags:
- contacts
summary: Get all the contacts
description: This displays all the contacts present for the user.
operationId: getContact
produces:
- application/json
- application/xml
responses:
200:
description: successful operation
schema:
$ref: '#/definitions/AllContacts'
400:
description: Invalid id supplied
404:
description: Contact not found
500:
description: Server error
definitions:
AllContacts:
type: array
items:
- $ref: '#/definitions/ContactModel1'
- $ref: '#/definitions/ContactModel2'
ContactModel1:
type: object
properties:
id:
type: integer
example: 1
firstName:
type: string
example: 'someValue'
lastName:
type: string
example: 'someValue'
ContactModel2:
type: object
properties:
id:
type: integer
example: 2
firstName:
type: string
example: 'someValue1'
lastName:
type: string
example: 'someValue1'
For some reason, it only returns the second object not the whole array of objects.
I am using OpenAPI 2.0 and suspect that the arrays are not well supported in this version.
An array of objects is defined as follows. The value of items must be a single model that describes the array items.
definitions:
AllContacts:
type: array
items:
$ref: '#/definitions/ContactModel'
ContactModel:
type: object
properties:
id:
type: integer
example: 1
firstName:
type: string
example: Sherlock
lastName:
type: string
example: Holmes
By default, Swagger UI displays the array examples with just one item, like so:
[
{
"id": 1,
"firstName": "Sherlock",
"lastName": "Holmes"
}
]
If you want the array example to include multiple items, specify the multi-item example in the array model:
definitions:
AllContacts:
type: array
items:
$ref: '#/definitions/ContactModel1'
example:
- id: 1
firstName: Sherlock
lastName: Holmes
- id: 2
firstName: John
lastName: Watson
I realise this is a bit offtopic, but I landed here looking for an example for OpenApi 3.0. For others looking for the same thing, this is how to do it:
paths:
/product-category:
get:
summary: 'Returns all product categories'
operationId: readProductCategory
tags:
- productCategory
responses:
'200':
description: 'Details about all product categories'
content:
application/json:
schema:
type: array
items:
allOf:
- $ref: '#/components/schemas/Identifier'
- $ref: '#/components/schemas/ProductCategory'
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
I'm fairly new to swagger and would appreciate some direction on good resources for learning.
I have a test project that I'm putting together and I am running into some issues.
I'm getting an error saying that the "parameters" in my "delete" block is not valid. It looks ok to me from what I've seen in the examples. But apparently I'm missing something. Any ideas?
swagger: "2.0"
info:
version: "2"
title: My Title
description: Provides services for vacation rentals site
termsOfService: Private
contact:
name: My Name
url: www.myurl.com
email: my#email.address
license:
name: MIT
url: http://opensource.org/licenses/MIT
schemes:
- http
host: myurl.com
basePath: /api
paths:
/guestbook:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of posts
schema:
type: array
items:
required:
- firstName
properties:
firstName:
type: string
lastName:
type: string
email:
type: string
comment:
type: string
post:
summary: Adds a comment to the guestbook
description: Adds a comment to the guestbook
parameters:
- name: firstname
in: formData
required: true
type: string
- name: lastname
in: formData
required: true
type: string
- name: email
in: formData
required: true
type: string
- name: comment
in: formData
required: true
type: string
responses:
201:
description: Shows a successful post
'405':
description: Invalid input
/guestbook/{id}:
get:
summary: Gets a single post
description: Returns a single post
operationId: getPost
parameters:
- name: id
in: path
description: ID of pet to fetch
required: true
type: integer
format: int64
responses:
200:
description: A list of posts
schema:
type: array
items:
required:
- firstName
properties:
id:
type: number
firstName:
type: string
lastName:
type: string
email:
type: string
comment:
type: string
delete:
summary: Removes a post
description: Removes a post
operationId: deletePost
parameters:
- name: id
in: path
responses:
200:
description: Post has been removed
You just need to describe the id parameter in the delete /guestbook/{id} operation just like you did in get /guestbook/{id}.
delete:
summary: Removes a post
description: Removes a post
operationId: deletePost
parameters:
- name: id
in: path
description: ID of pet to fetch
required: true
type: integer
format: int64
responses:
200:
description: Post has been removed
You can also define this parameter once for all operations of path /guestbook/{id}:
/guestbook/{id}:
parameters:
- name: id
in: path
description: ID of pet to fetch
required: true
type: integer
format: int64
get:
summary: Gets a single post
description: Returns a single post
operationId: getPost
responses:
200:
description: A list of posts
schema:
type: array
items:
required:
- firstName
properties:
id:
type: number
firstName:
type: string
lastName:
type: string
email:
type: string
comment:
type: string
delete:
summary: Removes a post
description: Removes a post
operationId: deletePost
responses:
200:
description: Post has been removed
If you need to learn how to write OpenAPI (fka. Swagger) specification files, you can read my Writing OpenAPI/Swagger Specification Tutorial