In OpenApi 3.0 how do I pass string array inside requestBody?
I'm able to pass it as member of class, but since it is class with one field only, I'm looking for simpler solution.
When using:
requestBody:
content:
'*/*':
schema:
type: array
items:
type: string
required: true
I get error 415.
Looks like using application/json content does the trick. Although string array is not a typical json, it is treated as one.
Related
I am using NestJS/mongoose in my project. All straightforward filters are working fine, but when I try to filter with nested data.
eg.
interface abc{
id: mongoose.Schema.Types.ObjectId
name: string
}
interface pqr{
prop1: string
prop2: string
prop3: abc
prop4: abc
}
interface xyz {
key1: string
key2: string
key3: pqr
}
While querying {"key3.prop3.id":new ObjectId("62ceb429804e78434d21af4e")} responds with the correct result inside NestJS project. but if I query through a network request, I can't send ObjectID as it gets covered into a string and as a result, it responds with an empty array.
Is there any way to match both ObjectId as well as string for the query.
If any way to add an operator to change it to ObjectId will also be acceptable like
{"$or":[{"key3.prop3.id":{"$oid":"62ceb429804e78434d21af4e"}},...]}
will gets chnaged into
{"$or":[{"key3.prop3.id":new ObjectId("62ceb429804e78434d21af4e")},...]}
I think that you should first convert the request string to mongoId/ObjectId using the next lines of code.
const { ObjectId } = require('mongodb');
const _id = ObjectId(req.id); // if your sting is by the name id and inside the request object
You can find more about this, in this stackoverflow question
I need to define a header parameter like this X-Custom: id1=uuid1;id2=uuid3
Since this is a common header for all paths I want to define it once and reference it every time. So far I came up with this:
openapi: 3.0.3
components:
parameters:
customHeader:
name: "X-Custom"
in: header # <--- produces error
required: true
schema:
type: object
properties:
id1:
type: string
format: uuid
id2:
type: string
format: uuid
style: matrix
explode: true
But I get an error that 'header' is not allowed and the parameter does not show up in the preview.
Any idea what's wrong?
OpenAPI 3 supports only style: simple for header parameters. This means that objects can be serialized in one of two ways:
# {"id1": "uuid1", "id2": "uuid2"} becomes...
# explode: false
X-Custom: id1,uuid1,id2,uuid2
# explode: true
X-Custom: id1=uuid1,id2=uuid2
Note that none of these styles match your expected format X-Custom: id1=uuid1;id2=uuid2 with ; as a separator. In fact, OpenAPI currently does not have a way to define ;-separated header values.
The most you can do is define the entire header as a string, mention the header value format in the description, and provide an example value:
customHeader:
name: X-Custom
in: header
required: true
schema:
type: string
example: id1=uuid1;id2=uuid2
There are existing feature requests to improve header serialization styles in OpenAPI:
Support for structured-headers de/serialization
Make it easier to define link headers
If you are designing a new API rather than documenting an existing one, another workaround is to split the header into two headers:
X-id1: uuid1
X-id2: uuid2
I'm implementing an OpenAPI-3.0 spec for my API, and I plan on using sparse fieldsets as a parameter for GETs. The examples for parameters using style=deepObject are a little sparse, so I'm not sure if I've got this exactly right.
- in: query
name: fields
style: deepObject
schema:
type: object
additionalProperties:
type: string
Can I combine both the deepObject and additionalProperties options?
I want to support flexible query parameter inputs like this:
GET /articles?include=author&fields[articles]=title,body&fields[people]=name
but I don't want to have to spell out every single option for each resource and field.
Your definition is correct. You might also need to add allowReserved: true so that the comma in =title,body is not percent-encoded, and you can add a parameter example value for documentation purposes:
- in: query
name: fields
style: deepObject
allowReserved: true
schema:
type: object
additionalProperties:
type: string
example:
articles: title,body
people: name
When using "try it out" in Swagger UI, enter the parameter value in the JSON format like so:
{
"articles": "title,body",
"people": "name"
}
Swagger UI will serialize the parameter as
?fields[articles]=title,body&fields[people]=name
I am defining a REST API in OpenAPI3 (Swagger).
I have an API that has a POST which uses a Model I have defined in teh components section as follows:
post:
summary: "Used to add some data"
operationId: postMyData
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MyModel'
required: true
components:
schemas:
MyModel:
type: object
properties:
SomeProperty1:
type: string
SomeProperty2:
type: string
SomeProperty3:
$ref: '#/components/schemas/SomeOtherModel'
SomeProperty4:
type: string
Now I have a PATCH API call that I want to use to update only some data of MyModel, e.g. SomeProperty1 and SomeProperty4.
Should I define a new Model for this PATCH operation? like so:
MyPATCHModel:
type: object
properties:
SomeProperty1:
type: string
SomeProperty4:
type: string
And then use this new MyPATCHModel in the requestBody of the PATCH operation? What is the standard practice here as I will have several API that are similar to this.
Check the docs on combining JSON schemas.
In your case you could for example define a shared MyModel schema with the two properties used in the PATCH method, and then another NewMyModel schema that uses allOf to combine MyModel with the POST-only properties.
Check this question for a concrete example.
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.