Node js swagger响应描述

Question

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

Answer 1

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 .