如何为嵌套对象编写 swagger 文档

问题描述

本文档已准备好用于 Nodejs 创建 API，如何为嵌套对象编写 swagger 文档。 下面是我完整的 swagger 文档代码。但它不显示用户对象。帮我解决问题

@swagger
/api/v1/employees/add:
  post:
    tags:
      - Employees
    summary: "Create a new employee"
    description:  
    produces:
      - application/json
    security:
     - api_key: []
     - api_token : [] 
    parameters:
      - name: body
        in: body
        description:
        required: true
        schema:
            type: "object"
            properties:
              employee_code:
               type: "string"
              mobilenumber:
               type: "string"
              firstname:  
               type: "string"
              lastname:
               type: "string"
              emailid:
               type: "string"
              is_login_enabled:
               type: "boolean"
              address_line1:  
               type: "string"
              address_line2:
               type: "string"
              town:
               type: "string"
              city:
               type: "string"
              state:  
               type: "string"
              pincode:
               type: "string"
              designation:
               type: "string"
              joining_date:
               type: "string"
               format: "date-time"
              releiving_date:
               type: "string"
               format: "date-time"
              is_active:  
               type: "boolean"
              account_id:  
               type: "number"
        user:
            type: "object"
            properties:
              username:
               type: "string"   
              role_id:
               type: "number"
              reference_object:  
               type: "string"
               example: "employees"
              password:
               type: "string"
              password_secret:
               type: "string"
    responses:
      200:
        description: Employee created successfully
      204:
        description: No data found

这是 swagger ui 的快照

解决方法

对于嵌套对象很简单，只需在下面定义带有标识的属性，这样您的路由定义就会是

@swagger
/api/v1/employees/add:
  put:
    tags:
      - Employees
    summary: "Create a new employee"
    description:  
    produces:
      - application/json
    security:
     - api_key: []
     - api_token : [] 
    parameters:
      - name: body
        in: body
        description:
        required: true
        schema:
           type: "object"
           properties:
              employee_code:
                 type: "string"
              mobilenumber:
                 type: "string"
              firstname:  
                 type: "string"
              lastname:
                 type: "string"
              emailid:
                 type: "string"
              is_login_enabled:
                 type: "boolean"
              address_line1:  
                 type: "string"
              address_line2:
                 type: "string"
              town:
                 type: "string"
              city:
                 type: "string"
              state:  
                 type: "string"
              pincode:
                 type: "string"
              designation:
                 type: "string"
              joining_date:
                 type: "string"
                 format: "date-time"
              releiving_date:
                 type: "string"
                 format: "date-time"
              is_active:  
                 type: "boolean"
              account_id:  
                 type: "number"
              user:
                 type: "object"
                 properties:
                    username:
                       type: "string"   
                    role_id:
                       type: integer
                    reference_object:  
                       type: "string"
                       example: "employees"
                    password:
                       type: "string"
                    password_secret:
                       type: "string"
    responses:
      200:
        description: Employee created successfully
      204:
        description: No data found

它在 Swagger UI 中看起来像这样。

确保在放置时有正确的想法。