API require to pass POST body as form object. For example how Postman makes requests:
curl -X POST \
http://api.mysite.local/v1/site/login \
-H 'cache-control: no-cache' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F 'LoginForm[login]=username' \
-F 'LoginForm[password]=password'
How can I describe this with OpenAPI 3.0? Due to large amount of reusable forms and data objects, I desided to place them in /components/schemas and reuse in request description with $ref:
paths:
/site/login:
description: "Authorization"
post:
requestBody:
content:
application/x-www-form-urlencoded:
type: object
properties:
LoginForm:
$ref: "components/schemas/LoginForm"
encoding:
LoginForm:
style: deepObject
explode: true
components:
schemas:
LoginForm:
type: object
properties:
login:
type: string
password:
type: string
required:
- login
- password
Unfortunately that did not worked, when I execute widdershins --expandBody 'api.yml' -o 'api.md', body parameters section is empty. Whad I do wrong?
Related
I've the following dto:
export class CreatePersonDto {
#IsString()
#ApiProperty({
description: 'Person name',
example: 'Jhon Doe',
})
readonly name: string;
#ValidateIf((object, value) => value)
#IsString({ each: true })
#ApiProperty({
description: 'Clothes ids',
isArray: true,
type: String,
})
readonly clothes: string[];
}
This is the cURL generated by Swagger Ui:
(Unable to parse this in NestJs to a string array)
curl -X 'POST' \
'http://localhost:3000/person' \
-H 'accept: */*' \
-H 'Content-Type: multipart/form-data' \
-F 'name=Jhon Doe' \
-F 'clothes=id1,id2'
(Clothes are sent as a string)
The array form in the UI looks like this:
This is the expected cURL (Generated by postman, or manually):
(Nestjs automatically parse this to an array)
curl -X 'POST' \
'http://localhost:3000/person' \
-H 'accept: */*' \
-H 'Content-Type: multipart/form-data' \
-F 'name=Jhon Doe' \
-F 'clothes[0]=id1' \
-F 'clothes[1]=id2'
(Clothes are correctly send as an array)
How can i solve this problem with swagger?
I'm making API documentation on swagger and using YAML.
This is my YAML code
swagger: "2.0"
info:
title: Sign_up Api
description: This Will alow user to Signup.
version: 1.0.0
host: e9ea53234b75.ngrok.io
basePath: /customer_app/api/v1
schemes:
- https
paths:
/sign_up:
post:
summary: Return User Credentials After signup.
parameters:
- in: body
name: body
required: true
# type: string
schema:
type: object
properties:
email:
type: string
example: test123#gmail.com
password:
# type: string
example: test123
password_confirmation:
# type: integer
example: test123
name:
type: string
example: testabc
description: User can be signup by providing the listed params & it will return a authentication token and other user params.
produces:
- application/json
responses:
200:
description: User credentials.
properties:
id:
type: string
example: 70020ed1-50fe-4c7e-afed
password:
# type: string
example: pasw123
password_confirmation:
# type: string
example: pasw123
name:
type: string
example: testabc
422:
description: The specified email is invalid (e.g. not following the syntax) or paswwords are not same or missing params.
default:
description: Unexpected error
and im getting my params in rails by
params.require(:user).permit(:email, :password , :password_confirmation, :uuid, :name)
in this way I'm sending my params from the postman
and getting this response
<ActionController::Parameters {"user"=><ActionController::Parameters {"email"=>"moon123#gmail.com", "password"=>"moon123", "password_confirmation"=>"moon123", "name"=>"moon123"} permitted: false>, "format"=>:json, "controller"=>"customer_app/api/v1/registrations", "action"=>"create"} permitted: false>
but by using user[email] in YAML got this in a wrong way
<ActionController::Parameters {"user[email]"=>"test123#gmail.com", "user[password]"=>"test123", "user[password_confirmation]"=>"test123", "user[name]"=>"testabc", "format"=>:json, "controller"=>"customer_app/api/v1/registrations", "action"=>"create", "registration"=>{"user[email]"=>"test123#gmail.com", "user[password]"=>"test123", "user[password_confirmation]"=>"test123", "user[name]"=>"testabc"}} permitted: false>
I don't know how to edit my YAML to get the response as I got from Postman.
Postman's "form-data" bodies are for requests with Content-Type: multipart/form-data. In OpenAPI 2.0, such requests need to have consumes: [multipart/form-data], and the body fields are defined as in: formData parameters.
swagger: '2.0'
...
paths:
/sign_up:
post:
summary: Return User Credentials After signup.
consumes:
- multipart/form-data
parameters:
- in: formData
name: user[email]
type: string
format: email
x-example: test123#gmail.com
- in: formData
name: user[password]
type: string
format: password
x-example: test123
- in: formData
name: user[password_confirmation]
type: string
format: password
x-example: test123
- in: formData
name: user[name]
type: string
x-example: testabc
I am trying to generate the API documentation using swagger editor. I specified my API specification as follow
paths:
/opendata/v1/{index}:
get:
tags: [verification]
description: Verify the person information
parameters:
- name: index
in: path
description: specific data index
required: true
type: string
- name: name
in: query
description: name of a person
required: false
type: string
- name: company name
in: query
description: name of a company
required: false
type: string
responses:
'200':
description: Success
content:
application/json:
schemas:
$ref: '#/responses/200'
responses:
'200':
description: Success
schema:
type: object
properties:
verification:
type: string
But its always showing error in the editor that "Not a valid response definition". I checked the specification for response from here. What changes I should do so that error will not come.
Note: I want the response in the json form like below:
{
verification:string
}
You are mixing OpenAPI/Swagger 2.0 and OpenAPI 3.0 syntax. Your spec seems to be swagger: '2.0', so you should use:
paths:
/opendata/v1/{index}:
get:
...
produces:
- application/json
responses:
200:
$ref: '#/responses/200'
Here's a related OpenAPI/Swagger 2.0 guide: Describing Responses
Hi i am trying to send the Default values through body parameters but its Not taking while Submitting. can anybody please help me on this issue. Here is my code and i am trying to send the default name parameter through body
swagger: '2.0'
info:
version: 1.0.0
title: PetStore on Heroku
description: |
**This example has a working backend hosted in Heroku**
You can try all HTTP operation described in this Swagger spec.
Find source code of this API [here](https://github.com/mohsen1/petstore-api)
host: petstore-api.herokuapp.com
basePath: /pet
schemes:
- http
- https
consumes:
- application/json
- text/xml
produces:
- application/json
- text/html
paths:
/:
get:
parameters:
- name: limit
in: query
description: number of pets to return
type: integer
default: 0
responses:
200:
description: List all pets
schema:
title: Pets
type: array
items:
$ref: '#/definitions/Pet'
post:
parameters:
- name: pet
in: body
description: The pet JSON you want to post
schema:
$ref: '#/definitions/Pet'
required: true
responses:
200:
description: Make a new pet
put:
parameters:
- name: pet
in: body
description: The pet JSON you want to post
schema:
$ref: '#/definitions/Pet'
required: true
responses:
200:
description: Updates the pet
/{petId}:
get:
parameters:
- name: petId
in: path
type: string
description: ID of the pet
required: true
responses:
200:
description: Sends the pet with pet Id
definitions:
Pet:
type: object
properties:
name:
type: string
default : "xxxxxxx"
birthday:
type: integer
format: int32
The default value should be handled in the server side as the server should not always assume the client sends HTTP requests that are 100% conforming to the spec.
I think this can help you, if you are trying to send default data with your schema:
definitions:
Pet:
type: object
default:
name: xxxx
birthday: xxxx
properties:
name:
type: string
birthday:
type: integer
format: int32
I would like to convert following curl code to ruby.
curl -u "my_username":"my_pass" \
-X POST \
-F "positive_examples=#/Users/abc/Downloads/tiger.zip" \
-F "negative_examples=#/Users/abc/Downloads/leopard.zip" \
-F "name=tiger" \
"http://localhost/api/v2/class"
Finally, I could convert the curl example to Ruby, follow the example in ruby:
request = RestClient::Request.new(method: :post,
url: 'http://localhost/api/v2/class',
user: 'my_username',
password: 'my_pass',
payload: {multipart:true,
positive_examples:File.new("/Users/abc/Downloads/tiger.zip", 'rb'),
negative_examples:File.new("/Users/abc/Downloads/leopard.zip", 'rb')
name:'tiger'})
RestClient::Request.execute method: :post,
url: 'http://localhost/api/v2/class',
user: 'my_username',
password: 'my_pass',
payload: {
multipart: true,
positive_examples: File.new('/Users/abc/Downloads/tiger.zip', 'rb'),
negative_examples: File.new('/Users/abc/Downloads/leopard.zip', 'rb'),
name: 'tiger',
}
Simply read the gem's README.