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
Related
I have a swagger definition that has a query and a header that share the same name:
parameters:
qry_param:
name: appid
in: query
required: true
type: string
hdr_param:
name: appid
in: header
required: false
type: string
...
paths:
'/some/path/here':
post:
parameters:
- $ref: '#/parameters/hdr_param'
- $ref: '#/parameters/qry_param'
When I try to generate a client with swagger-codegen-maven-plugin only request header is generated for this parameter.
What can I do to generate both?
I'm trying to add the request body to a swagger file, but when I use requestBody, it keeps saying Additional properties not allowed: requestBody I tried multple -in parameters like this
parameters
- in: body
name: email
description: The user to create.
schema:
$ref: "#/definitions/User"
- in: body
name: password
description: The user to create.
schema:
$ref: "#/definitions/User"
but then it says Operation cannot have multiple body parameters So I'm not sure how to reference all the req.body values. Also what if I had multiple body parameters and an /:id path as well?
I'm still really new to swagger so I appreciate any help with this.
swagger: "2.0"
info:
version: "1.0.0"
title: Hello World App during dev, should point to your local machine
basePath: /v1
schemes:
# tip: remove http to make production-grade
- http
- https
paths:
/user/signup:
x-swagger-router-controller: user
post:
description: signup POST
operationId: signup
parameters:
- in: body
name: email
description: The user to create.
schema:
$ref: "#/definitions/User"
- in: body
name: password
description: The user to create.
schema:
$ref: "#/definitions/User"
responses:
"200":
description: Success got all the listings
schema:
$ref: "/definitions/User"
"500":
description: Unexpected Error
schema:
type: object
properties:
message:
type: string
/user/login:
x-swagger-router-controller: user
post:
description: Login request
operationId: login
parameters:
- in: body
name: login
description: The user to create.
schema:
$ref: "#/definitions/Login"
responses:
"200":
description: Success got all the listings
schema:
$ref: "/definitions/Login"
"500":
description: Unexpected Error
schema:
type: object
properties:
message:
type: string
definitions:
User:
properties:
id:
type: integer
email:
type: string
password:
type: string
instagramName:
type: string
over21:
type: boolean
role:
type: string
fullName:
type: string
address1:
type: string
address2:
type: string
city:
type: string
state:
type: string
zip:
type: string
passwordCreated:
type: string
Login:
properties:
id:
type: string
email:
type: string
password:
type: string
You don't need multiple in: body parameters, you have them all defined already in the User schema (each request has just one body anyways).
That is exactly how it should be done. Just remove the second 'body' and maybe rename the other one:
parameters:
- in: body
name: user
description: The user to create.
schema:
$ref: "#/definitions/User"
If you require a path parameter you can define it as in: path. You need to add it to the path itself as well:
paths:
/user/signup/{id}:
x-swagger-router-controller: user
post:
description: signup POST
operationId: signup
parameters:
- in: path
name: id
description: User id
type: string
required: true
- in: body
name: user
description: The user to create.
schema:
$ref: "#/definitions/User"
In contradiction to in: body you can have multiple in: path parameters. Path parameters must include required: true.
Swagger.yml
swagger: "2.0"
info:
version: "0.0.1"
title: Movie DB
# during dev, should point to your local machine
host: localhost:8000
# basePath prefixes all resource paths
basePath: /
#
schemes:
# tip: remove http to make production-grade
- http
- https
# format of bodies a client can send (Content-Type)
consumes:
- application/json
# format of the responses to the client (Accepts)
produces:
- application/json
paths:
/movies:
# binds a127 app logic to a route
x-swagger-router-controller: movies
get:
description: Returns 'Hello' to the caller
# used as the method name of the controller
operationId: index
parameters:
- name: name
in: query
description: The name of the person to whom to say hello
required: false
type: string
responses:
"200":
description: Success
schema:
# a pointer to a definition
$ref: "#/definitions/MovieListBody"
# responses may fall through to errors
default:
description: Error
schema:
$ref: "#/definitions/ErrorResponse"
/swagger:
x-swagger-pipe: swagger_raw
# complex objects have schema definitions
post:
description: Creates a new movie entry
operationId: create
parameters:
- name: movie
required: true
in: body
description: a new movie details
schema:
$ref: "#/definitions/MovieBody"
responses:
"200":
description: a successfully stored movie details
schema:
$ref: "#/definitions/MovieBody"
default:
description: Error
schema:
$ref: "#/definitions/ErrorResponse"
definitions:
MovieListBody:
required:
- movies
properties:
movies:
type: array
items:
$ref: "#/definitions/Movie"
Movie:
required:
- title
- gener
- year
properties:
title:
type: string
gener:
type: string
year:
type: integer
MovieBody:
required:
- movie
properties:
movie:
$ref: "#/definitions/Movie"
ErrorResponse:
required:
- message
properties:
message:
type: string
I Get this error:
Route defined in Swagger specification (/movies) but there is no defined post operation
I am new to this concept of Swagger API. I tried crud operation in Swagger API. The get method is working fine, but I tried post showing this type of issue. I tried step by step watching Swagger API videos. I tried get function is data successfully retrieved in db.but I tried post data to mongodb using Swagger API it's throwing this type of error....
How to fix it? Can anyone suggest any solution?
You don't need the /swagger node, just a post node at the same level as the get node under /movies path.
POST and GET are operations that can be performed on the 'movies' endpoint.
At present, your swagger supports GET /movies/ and POST /swagger/ as you've got a path called 'swagger'.
The structure should become:
paths:
/movies:
get:
# All the get properties
post:
# All the post properties
definitions:
# All the definitions you need
And here's an updated copy of your swagger:
swagger: "2.0"
info:
version: "0.0.1"
title: Movie DB
# during dev, should point to your local machine
host: localhost:8000
# basePath prefixes all resource paths
basePath: /
#
schemes:
# tip: remove http to make production-grade
- http
- https
# format of bodies a client can send (Content-Type)
consumes:
- application/json
# format of the responses to the client (Accepts)
produces:
- application/json
paths:
/movies:
# binds a127 app logic to a route
x-swagger-router-controller: movies
get:
description: Returns 'Hello' to the caller
# used as the method name of the controller
operationId: index
parameters:
- name: name
in: query
description: The name of the person to whom to say hello
required: false
type: string
responses:
"200":
description: Success
schema:
# a pointer to a definition
$ref: "#/definitions/MovieListBody"
# responses may fall through to errors
default:
description: Error
schema:
$ref: "#/definitions/ErrorResponse"
post:
description: Creates a new movie entry
operationId: create
parameters:
- name: movie
required: true
in: body
description: a new movie details
schema:
$ref: "#/definitions/MovieBody"
responses:
"200":
description: a successfully stored movie details
schema:
$ref: "#/definitions/MovieBody"
default:
description: Error
schema:
$ref: "#/definitions/ErrorResponse"
definitions:
MovieListBody:
required:
- movies
properties:
movies:
type: array
items:
$ref: "#/definitions/Movie"
Movie:
required:
- title
- gener
- year
properties:
title:
type: string
gener:
type: string
year:
type: integer
MovieBody:
required:
- movie
properties:
movie:
$ref: "#/definitions/Movie"
ErrorResponse:
required:
- message
properties:
message:
type: string
This question already has answers here:
Post a json body with swagger
(1 answer)
How to describe this POST JSON request body in OpenAPI (Swagger)?
(3 answers)
Closed 2 years ago.
swagger: "2.0"
info:
version: "1.0.0"
title: "CCA API"
host: localhost:1337
basePath: /v1
schemes:
- http
consumes:
- application/json
produces:
- application/json
paths:
/user/login:
post:
description: Access a user account
summary: User Account Access
operationId: loginAccount
parameters:
- name: email
dataType: string
in: body
required: true
description: Your email
- name: password
dataType: string
in: body
required: true
description: Your password
responses:
"200":
description: Successfully signed in
schema:
type: object
properties:
email:
type: string
firstName:
type: string
lastName:
type: string
token:
type: string
userType:
type: string
401:
description: Invalid email or password.
Which is a correct way to write yaml file?
I have this error: "Not a valid parameter definition"
in each declaration of the parameters...
I would also like to know the correct way to integrate Sails JS with Swagger?
As Vantroys said dataType is not the correct key. It's type.
But in this case you try to define an post method and need to define some type of input data, like in the example below.
Have look at the pet store example from swagger itself:
https://editor.swagger.io/
parameters:
- in: "body"
name: "body"
description: "Pet object that needs to be added to the store"
required: true
schema:
$ref: "#/definitions/Pet"
Concerning your parameters : I think you have to use "type", and not "dataType" :
parameters:
- name: email
type: string
in: body
required: true
description: Your email
- name: password
type: string
in: body
required: true
description: Your password
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