How do I specify an array as a parameter? For instance, post to /persons can be given strings username, firstname, and lastname, and array myArray.
paths:
/persons:
post:
parameters:
- name: person_what_is_the_purpose_of_this
in: body
description: The person to create.
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
myArray:
type: array
items:
properties:
myArrayElement:
type: string
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
swagger: "2.0"
info:
version: "1.0.0"
title: Swagger Petstore
host: petstore.swagger.io
basePath: /v2
schemes:
- http
paths:
/pets/findByStatus:
get:
parameters:
- in: query
name: status
type: array
items:
type: string
responses:
"200":
description: successful operation
schema:
type: array
items:
type: object
required:
- name
- photoUrls
properties:
id:
type: integer
format: int64
category:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
name:
type: string
example: doggie
photoUrls:
type: array
items:
type: string
tags:
type: array
items:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
"400":
description: Invalid status value
You need to specify collectionFormat: multi
For your array it would look like this, be sure to put it on the same level as the type:
myArray:
type: array
collectionFormat: multi
Documentation about arrays
Related
I'm trying to determine how I can set up a request in a manner that makes it easier for end users to interact with it:
so given that Pet is defined as such:
#/components/schemas/Pet
Pet:
x-swagger-router-model: io.swagger.petstore.model.Pet
required:
- name
properties:
id:
type: integer
format: int64
example: 10
name:
type: string
example: doggie
category:
$ref: '#/components/schemas/Category'
status:
type: string
description: pet status in the store
enum:
- available
- pending
- sold
type: object
ApiResponse:
properties:
code:
type: integer
format: int32
type:
type: string
message:
type: string
type: object
and Category is defined as:
#/components/schemas/Category
x-swagger-router-model: io.swagger.petstore.model.Category
properties:
id:
type: integer
format: int64
example: 1
name:
type: string
example: Dogs
xml:
name: category
type: object
and the way to add a new object is by using this POST:
paths:
/pet:
post:
tags:
- pet
summary: Add a new pet to the store
description: Add a new pet to the store
operationId: addPet
responses:
'200':
description: Successful operation
content:
application/xml:
schema:
$ref: '#/components/schemas/Pet'
application/json:
schema:
$ref: '#/components/schemas/Pet'
'405':
description: Invalid input
security:
- petstore_auth:
- 'write:pets'
- 'read:pets'
requestBody:
description: Create a new pet in the store
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Pet'
How do i generate a POST with this format:
{
"id": 10,
"name": "doggie",
"category": 1,
"status": "available"
}
instead of this:
{
"id": 10,
"name": "doggie",
"category": {
"id": 1,
"name": "Dogs"
},
"status": "available"
}
I understand that I can set up a different schema for POST by specifying that for this type of request i would use an int for the category, but was hoping there would be a way to maintain the appropriate referencing of the pet.category to the category.
any ideas would be appreciated.
ps note that the reference for this example is directly accessible here
I have these three models:
Task.js
name: String
Question.js
score: Number,
task_id: { type: mongoose.Types.ObjectId, ref: 'Task', alias: 'task' },
problem_id: { type: mongoose.Types.ObjectId, ref: 'Problem', alias: 'problem' },
Problem.js
name: String
How can I count the number of tasks that matches a certain task name and has a question that is connected to a problem that matches a certain problem id?
Let's say I have this case classes as part of some OAS3 specification:
case class UserData(userId: String, country: Country)
case class Country(id: String, name: String)
Then, the OAS3 specification would be something like this:
components:
schemas:
UserData:
type: object
properties:
userId:
type: string
country:
$ref: '#/components/schemas/Country'
Country:
type: object
properties:
id:
type: string
name:
type: string
My question is: If a made country as Option, how can I model this?
case class UserData(userId: String, country: Option[Country])
case class Country(id: String, name: String)
I try putting "nullable: true" but this is not valid:
components:
schemas:
UserData:
type: object
properties:
userId:
type: string
country:
nullable: true <---- NOT VALID
$ref: '#/components/schemas/Country'
Country:
type: object
properties:
id:
type: string
name:
type: string
How can I model this Option?
Mark all of the non optional parameters as required:
components:
schemas:
UserData:
required:
- userId
type: object
properties:
userId:
type: string
country:
$ref: '#/components/schemas/Country'
Country:
required:
- id
- name
type: object
properties:
id:
type: string
name:
type: string
I have this component:
components:
schemas:
book:
type: object
required:
- id
properties:
id:
type: string
title:
type: string
author:
type: string
Is there a way to define a response object that includes the book attributes using this component? The response is this:
{
"id": "xxxxx",
"title": "This is title",
"author": "John"
}
I tried like this:
responses:
200-response:
description: HTTP 200 response
content:
application/json:
schema:
type: object
properties:
book:
$ref: '#/components/schemas/book'
but it has the parent object of book instead of the attributes immediately.
You're almost there. Just put the schema $ref directly under schema.
responses:
200-response:
description: HTTP 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/book'
I have the following object structure in my database
{
partnerName: '24 Fitness',
supportedProducts: [
'FitBit',
'Protein Powder'
]
},
where the key value supportedProducts can be modified from the client side.
I am constructing a PATCH API method using swagger documentation to support the above functionality. But I am unsure of the patch object definition, as documentation doesn't provide an detailed example of constructing a PATCH.
The current definition that I have ends up in error upon execution and looks like as following
"patch":{
"description":"Update supported products for a partner",
"operationId":"Update supported products",
"parameters":[
{
"name": "partnerName",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "supportedProducts",
"in": "body",
"required": true,
"schema":{
"$ref":"#/definitions/PatchRequest"
}
}
],
"responses":{
"200":{
"description": "product updated"
},
"404":{
"description": "Not Found"
}
}
"definitions": {
"PatchRequest":{
"type": "object",
"required":[
"partnerName",
"supportedProducts"
],
"properties":{
"partnerName":{"type": "string"},
"supportedProducts":{
"type": "array",
"items":{"type": "string"}
}
}
}
}
For this simple case, I would use a JSON Patch object to describe the operations to make on the target.
Here is an example of a JSON Patch Swagger API.
paths:
/users/{GUID}:
patch:
summary: Update a user
parameters:
- name: GUID
in: path
required: true
type: string
format: GUID
description: The GUID of a specific user
- name: JsonPatch
in: body
required: true
schema:
$ref: "#/definitions/PatchRequest"
responses:
'200':
description: Successful response
schema:
$ref: "#/definitions/User"
definitions:
PatchRequest:
type: array
items:
$ref: "#/definitions/PatchDocument"
PatchDocument:
description: A JSONPatch document as defined by RFC 6902
required:
- "op"
- "path"
properties:
op:
type: string
description: The operation to be performed
enum:
- "add"
- "remove"
- "replace"
- "move"
- "copy"
- "test"
path:
type: string
description: A JSON-Pointer
value:
type: object
description: The value to be used within the operations.
from:
type: string
description: A string containing a JSON Pointer value.
For OpenApi 3.0.x the structure of the .yaml file has changed. A valid definition could look like:
components:
requestBodies:
PatchBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchBody'
schemas:
PatchBody:
type: array
items:
$ref: "#/components/schemas/PatchDocument"
PatchDocument:
type: object
description: A JSONPatch document as defined by RFC 6902
required:
- "op"
- "path"
properties:
op:
type: string
description: The operation to be performed
enum:
- "add"
- "remove"
- "replace"
- "move"
- "copy"
- "test"
path:
type: string
description: A JSON-Pointer
value:
type: object
description: The value to be used within the operations.
from:
type: string
description: A string containing a JSON Pointer value.
patch:
parameters:
- $ref: '#/components/parameters/objectId'
requestBody:
$ref: '#/components/requestBodies/PatchBody'
responses:
...
Since the JSON Patch format is well defined by RFC 6902 I think it would be sufficient (at least for OpenAPI 3) to specify the content type defined in the RFC, and since it seems to be necessary to define either a schema or example (at least in my swagger editor), to also specify type: string and format: JSON Patch or format: RFC 6902.
It doesn't make sense to redefine a format that is already well defined by the RFC.
Example:
paths:
/users/{GUID}:
patch:
summary: Update a user
parameters:
- name: GUID
in: path
required: true
type: string
format: GUID
description: The GUID of a specific user
requestBody:
content:
application/json-patch+json:
schema:
type: string
format: RFC 6902