Search code examples
node.jsswaggerswagger-ui

how to write swagger document for nested objects


this document is ready for Nodejs create API, how to write swagger document for nested objects. Here below is my full swagger document code. but it doesn't show user object. help me to fix the issue

@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

here is the snap of swagger ui image


Solution

  • For nested object it is simple just define properties below with an indentation so your route definition would be

    @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
    
    

    It looks like this in the Swagger UI. enter image description here

    Make sure to have the proper indentations when placing it.