Documenting Rails API POST action with params in body - swagger

Question

I am using Ruby on Rails to architect a Rest API for a client and trying to document it by using SwaggerHub.
I would like to know how to document a post action with the correct parameters in the BODY. So far I have the action created and need to describe the following parameters for my developers.
{"user": {"email":"999999#gmail.com", "password":"12345678", "password_confirmation":"12345678"}}
I have started out with this for my post action:
"post": {
"description": "Creates a user",
"produces": [
"application/json"
],
"consumes": [
"application/json"
],
"responses": {
"201": {
"description": "Creates an instance of User",
},
"422": {
"description": "Bad syntax, user not created"
}
}
}
It's easy to document with the parameters " in PATH like the Get or Delete action which has the user ID in the params like this
"delete": {
"description": "Destroy a user",
"produces": [
"application/json"
],
"consumes": [
"application/json"
],
"responses": {
"200": {
"description": "destory a single user",
},
"404": {
"description": "user not found"
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of user to use for action",
"required": true,
"type": "array",
"items": {
"type": "integer"
}
How can I document the parameters with params "in": "body" ?

Answer 1

You just need to add a parameters list within the post and add a parameter with in set to body.
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A parameter body example
paths:
/users:
post:
description: creates a user
produces:
- application/json
consumes:
- application/json
parameters:
- name: user
in: body
schema:
properties:
user:
properties:
email:
type: string
password:
type: string
password_confirmation:
type: string
responses:
201:
description: Creates an instance of User
422:
description: Bad syntax, user not created
You can find many information about the OpenAPI (fka. Swagger) Specification by reading the specification description and this tutorial (disclosure: I wrote it).