Node js swagger описание ответа

Question

Я разработал REST-сервис, используя Node Js и Express. У меня есть интеграция Swagger для определения API. Об услуге входа в систему это определение чванства, которое я использовал:

/**
* @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
*/

Но мой сервис дает мне ответ json:

{
"status": "ok",
"data": {
    "auth": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjViYzg3ZDFkOWNhNmRkNDM5MDI1YjA1MCIsImlhdCI6MTU0MTA5MzMxMSwiZXhwIjoxNTQxMTc5NzExfQ.3BIl0dIQg-cEU9fyM7BocKLHEugH8cws5_E-dmRVHZM",
    "faId": "HSo7q2o0",
    "roles": "Owner"
}

}

Как я могу описать этот ответ в описании чванства? Спасибо

Answer 1

Вы можете многое узнать о том, как форматировать определения Сваггера, используя актуальную спецификацию онлайн: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responsesDefinitionsObject

Действительно упрощенная версия того, что вы хотите, выглядела бы примерно так:

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

Возможно, вы захотите заполнить дополнительную информацию, касающуюся описаний, какие свойства требуются и т. Д. Вы можете прочитать о том, что они означают, по ссылке выше.

Кроме того, модели в Swagger определяются с использованием словаря JSON Schema, который вы можете прочитать больше о здесь .