i have developed a REST Service using Node Js and Express.
I have integrate Swagger to define api doc.
About login service this is the swagger definition that i used:
/**
* #swagger
* /api/v1.0/login:
* post:
* tags:
* - Login
* description: Login into system
* produces:
* - application/json
* parameters:
* - username: User
* description: The username of user
* in: body
* required: true
* - password: password
* description: Password of user
* in: body
* required: true
*
* responses:
* 200:
* description: Successfully login
*/
But my service gives me this response json:
{
"status": "ok",
"data": {
"auth": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjViYzg3ZDFkOWNhNmRkNDM5MDI1YjA1MCIsImlhdCI6MTU0MTA5MzMxMSwiZXhwIjoxNTQxMTc5NzExfQ.3BIl0dIQg-cEU9fyM7BocKLHEugH8cws5_E-dmRVHZM",
"faId": "HSo7q2o0",
"roles": "Owner"
}
}
How i can describe this response into swagger response description?
Thanks
You can learn a lot about how to format Swagger definitions using the actual specification online: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responsesDefinitionsObject
A really simplified version of what you want would look something like this:
responses:
200:
description: Successfully login
schema:
properties:
status:
type: string
data:
type: object
properties:
auth:
type: boolean
token:
type: string
faId:
type: string
roles:
type: string
You would probably want to fill in more information as far as descriptions, which properties are required, etc. You can read about what those mean in the link above.
Also, models in Swagger are defined using the JSON Schema vocabulary, which you can read more about here.
Related
For example I have 2 API operations:
GET v1/people/{id}
POST v1/people/{id}
Only one of these operations is shown in my Swagger UI API docs but I want both of them displayed. I have many examples where this is the case. In the Swagger documentation it states:
"Swagger defines a unique operation as a combination of a path and an HTTP method."
This would make me think what I want to do is possible as they are uniquely identified by the HTTP method.
If I change the path parameter for one in my swagger.yaml file they will both show.
eg:
GET v1/people/{personid}
POST v1/people/{id}
But I would rather keep them all standard otherwise my API docs will appear messy.
I am using swagger-ui-express 4.1.4.
/v1/people/{id}:
get:
summary: Get people.
security:
- cookieAuth: []
tags:
- People
parameters:
- in: path
name: id
required: true
schema:
type : integer
example: 123
responses:
'200':
description: OK
/v1/people/{id}:
post:
summary: Get people.
security:
- cookieAuth: []
tags:
- People
parameters:
- in: path
name: id
required: true
schema:
type : integer
example: 123
responses:
'200':
description: OK
Thanks for your help.
You can try same path with different method: https://swagger.io/docs/specification/paths-and-operations/.
paths:
/users/{id}:
summary: Represents a user
description: >
This resource represents an individual user in the system.
Each user is identified by a numeric `id`.
get:
...
patch:
...
delete:
...
In your example:
/v1/people/{id}:
get:
summary: Get people.
security:
- cookieAuth: []
tags:
- People
parameters:
- in: path
name: id
required: true
schema:
type : integer
example: 123
responses:
'200':
description: OK
post:
summary: Get people.
security:
- cookieAuth: []
tags:
- People
parameters:
- in: path
name: id
required: true
schema:
type : integer
example: 123
responses:
'200':
description: OK
I use swaggerHub for write the documentation of my new app Node but I have a problem with one api.
My API require two params.
Example : POST http://cloud.amazingwebsite.com/:service/:action
Ok, if you want to use this API, you must to give two values. My problem is that the doc of swaggerHub propose only examples with one param.
Please, do you have a example with two params ? Is it possible ? Thanks
If you do it like this:
"/{service}/{action}":
x-swagger-router-controller: serviceController
post:
summary: To perform an action
operationId: serviceAction
parameters:
- name: service
in: path
required: true
type: string
description: Request Path Param for service
- name: action
in: path
required: true
type: string
description: Request Path Param for Action
responses:
'200':
description: Success
schema:
"$ref": "#/definitions/SuccessResponse"
default:
description: Error
schema:
"$ref": "#/definitions/ErrorResponse"
definitions:
SuccessResponse:
type: object
ErrorResponse:
required:
- error
properties:
error:
type: string
I am writing a schema for two get routes where the result is an object like
{
"id":"49077acb6ac8",
"info":
{
"name":"test"
}
}
Actually I got this :
/*
* #swagger
* definitions:
* getVCenter:
* id:
* type: string
* format: uuid
* info:
* type: object
* properties:
* name:
* type: string
* fullName:
* type: string
* vendor:
* type: string
* /v1/vcenters/:
* get:
* tags:
* - vcenters
* summary: Get availables vCenters.
* description: Get a list of availables vCenters.
* produces:
* - application/json
* responses:
* 200:
* description: an array of vCenters
* schema:
* $ref : '#definitions/getVCenter'
*/
But it doesn't work anymore.
Can someone explain to me what I did wrong please?
There are syntax errors in your annotation.
The indentation of info properties should be as follows:
* info:
* type: object
* properties: # <-- "properties" must be on the same level as "type: object"
* name:
* type: string
* fullName:
* type: string
* vendor:
* type: string
In $refs, there must be a / after # - replace #definitions with #/definitions:
$ref : '#/definitions/getVCenter'
Also, if the response is supposed to be "an array of vCenters" and not a single vCenter, then the response schema should be:
* responses:
* 200:
* description: an array of vCenters
* schema:
* type: array
* items:
* $ref : '#/definitions/getVCenter'
I'm trying to define a post endpoint using swagger, but it isn't allowing the requestBody parameter:
/names/{roster}:
get:
#...
post:
x-swagger-router-controller: names
description: Adds or removes name(s)
operationId: manageNames
parameters:
- name: roster
in: path
description: the roster to use
type: string
required: true
requestBody:
content:
'application/json':
schema:
$ref: '#/definitions/ManageNamesRequest'
when I run npm start, I get this:
API Errors:
#/paths/~1names~1{roster}/post: Additional properties not allowed: requestBody
1 error and 0 warnings
What's wrong with my spec?
You are probably mixing OpenAPI/Swagger 2.0 and OpenAPI 3.0 syntax. Your spec seems to be 2.0, but the requestBody keyword is a 3.0 feature. In 2.0, the request body is defined as a body parameter:
paths:
/names/{roster}:
post:
produces:
- application/json
...
parameters:
- ...
- in: body
name: body
required: true
schema:
$ref: '#/definitions/ManageNamesRequest'
More info: Describing Request Body
I am using node-swagger. It's working fine. I want to post json body without defining the schema in details. For example below I don't want to specify object properties. Is there any way to do this?
/pets:
post:
description: Add new
parameters:
- name: id
in: body
description: data to post
required: true
type: object
responses:
'200':
description: A list of pets
schema:
type : string
It's not rendering the textarea to post json data.
Try this YAML:
---
swagger: '2.0'
info:
version: 0.0.0
title: Simple API
paths:
/:
post:
produces:
- application/json
parameters:
- in: body
name: id
required: true
schema:
"$ref": "#/definitions/inBody"
responses:
201:
description: Added
definitions:
inBody:
type: object
If you are using swagger-ui-express and swagger-jsdoc and don't wan to use definitions you can directly define in YAML on endpoint like this.
/**
* #swagger
* /pets:
* post:
* description: Add new
* produces:
* - application/json
* parameters:
* - name: id
* description: data to post
* in: body
* required: true
* schema:
* type: object
* responses:
* 201:
* description: Pet created
*/
Based on Open API 3 spec, for an empty body request, you should have a requestBody section like the following:
requestBody:
required: true
description: blabla.
content:
application/json:
schema:
type: object
nullable: true