feat(api): Enhance API documentation and functionality for clients, menus, and maintenance groups

- Added new DTO definitions for AssignMenusToClientRequest, MaintGroupCreateRequest, MaintGroupUpdateRequest, and related entities in swagger.yaml.
- Implemented CRUD operations for clients, including creating, updating, deleting, and retrieving clients with detailed API documentation.
- Introduced endpoints for assigning and removing menus from clients with appropriate request bodies.
- Enhanced maintenance group management with endpoints for creating, updating, deleting, and retrieving maintenance groups.
- Updated menu management with endpoints for creating, updating, deleting, and retrieving menus, including filtering and sorting capabilities.
- Refactored user-related endpoints to return a consistent response structure using utils.Response.

docs/swagger.yaml

@@ -1,5 +1,160 @@
 basePath: /api/v1
 definitions:
+  dto.AssignMenusToClientRequest:
+    properties:
+      menu_ids:
+        items:
+          type: string
+        type: array
+    required:
+    - menu_ids
+    type: object
+  dto.MaintGroupCreateRequest:
+    properties:
+      client_id:
+        type: string
+      code:
+        maxLength: 50
+        minLength: 2
+        type: string
+      description:
+        type: string
+      maintenance_group_roles:
+        items:
+          $ref: '#/definitions/dto.MaintenanceGroupRole'
+        type: array
+      name:
+        maxLength: 100
+        minLength: 2
+        type: string
+    required:
+    - client_id
+    - code
+    - maintenance_group_roles
+    - name
+    type: object
+  dto.MaintGroupUpdateRequest:
+    properties:
+      client_id:
+        type: string
+      code:
+        maxLength: 50
+        minLength: 2
+        type: string
+      description:
+        type: string
+      maintenance_group_roles:
+        items:
+          $ref: '#/definitions/dto.MaintenanceGroupRoleUpdate'
+        type: array
+      name:
+        maxLength: 100
+        minLength: 2
+        type: string
+    type: object
+  dto.MaintenanceGroupRole:
+    properties:
+      level:
+        type: integer
+      maintenance_group_role_users:
+        items:
+          $ref: '#/definitions/dto.MaintenanceGroupRoleUser'
+        type: array
+      role_id:
+        type: string
+    required:
+    - level
+    - maintenance_group_role_users
+    - role_id
+    type: object
+  dto.MaintenanceGroupRoleUpdate:
+    properties:
+      id:
+        type: string
+      level:
+        type: integer
+      maintenance_group_role_users:
+        items:
+          $ref: '#/definitions/dto.MaintenanceGroupRoleUser'
+        type: array
+      role_id:
+        type: string
+    type: object
+  dto.MaintenanceGroupRoleUser:
+    properties:
+      user_id:
+        type: string
+    required:
+    - user_id
+    type: object
+  dto.MenuCreateRequest:
+    properties:
+      icon_url:
+        maxLength: 100
+        minLength: 2
+        type: string
+      mode:
+        maxLength: 20
+        minLength: 8
+        type: string
+      name:
+        maxLength: 100
+        minLength: 2
+        type: string
+      parent_id:
+        type: string
+      sequence:
+        type: integer
+      status:
+        type: string
+      table_name:
+        maxLength: 10
+        type: string
+      url:
+        minLength: 8
+        type: string
+    required:
+    - mode
+    - name
+    - sequence
+    - url
+    type: object
+  dto.MenuUpdateRequest:
+    properties:
+      icon_url:
+        maxLength: 100
+        minLength: 2
+        type: string
+      mode:
+        maxLength: 20
+        minLength: 2
+        type: string
+      name:
+        maxLength: 100
+        minLength: 2
+        type: string
+      parent_id:
+        type: string
+      sequence:
+        type: integer
+      status:
+        type: string
+      table_name:
+        maxLength: 10
+        type: string
+      url:
+        minLength: 8
+        type: string
+    type: object
+  dto.RemoveMenusFromClientRequest:
+    properties:
+      menu_ids:
+        items:
+          type: string
+        type: array
+    required:
+    - menu_ids
+    type: object
   dto.SendVerificationEmailRequest:
     properties:
       email:
@@ -56,38 +211,6 @@ definitions:
     - email
     - password
     type: object
-  dto.UserResponse:
-    properties:
-      address:
-        type: string
-      email:
-        type: string
-      gender:
-        type: string
-      id:
-        type: string
-      name:
-        type: string
-      password:
-        type: string
-      phone:
-        type: string
-      photo_url:
-        type: string
-      roles:
-        items:
-          $ref: '#/definitions/dto.UserRolesResponse'
-        type: array
-      username:
-        type: string
-    type: object
-  dto.UserRolesResponse:
-    properties:
-      id:
-        type: string
-      name:
-        type: string
-    type: object
   dto.UserUpdateRequest:
     properties:
       address:
@@ -128,6 +251,39 @@ definitions:
     required:
     - token
     type: object
+  utils.PaginationResponse:
+    properties:
+      max_page:
+        type: integer
+      page:
+        type: integer
+      per_page:
+        type: integer
+      total:
+        type: integer
+    type: object
+  utils.Response:
+    properties:
+      data: {}
+      error: {}
+      message:
+        type: string
+      meta: {}
+      status:
+        type: boolean
+    type: object
+  utils.ResponseWithPagination:
+    properties:
+      code:
+        type: integer
+      data: {}
+      message:
+        type: string
+      pagination:
+        $ref: '#/definitions/utils.PaginationResponse'
+      status:
+        type: string
+    type: object
 externalDocs:
   description: OpenAPI
   url: https://swagger.io/resources/open-api/
@@ -207,6 +363,238 @@ paths:
       summary: Refresh auth token
       tags:
       - Auth
+  /clients:
+    get:
+      consumes:
+      - application/json
+      description: Get paginated list of clients with filtering and sorting capabilities
+      parameters:
+      - description: Filter by name (partial match)
+        in: query
+        name: name
+        type: string
+      - description: Filter by code (partial match)
+        in: query
+        name: code
+        type: string
+      - description: 'Page size (default: 10)'
+        in: query
+        name: per_page
+        type: integer
+      - description: 'Page number (default: 1)'
+        in: query
+        name: page
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.ResponseWithPagination'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/utils.Response'
+      summary: Get list of clients
+      tags:
+      - Clients
+    post:
+      consumes:
+      - multipart/form-data
+      description: Create a new client with the provided information
+      parameters:
+      - description: Client name
+        in: formData
+        name: name
+        required: true
+        type: string
+      - description: Client code
+        in: formData
+        name: code
+        required: true
+        type: string
+      - description: Client logo (optional)
+        in: formData
+        name: logo
+        type: file
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/utils.Response'
+      summary: Create a new client
+      tags:
+      - Clients
+  /clients/{id}:
+    delete:
+      consumes:
+      - application/json
+      description: Delete a client by ID
+      parameters:
+      - description: Client ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/utils.Response'
+      summary: Delete client
+      tags:
+      - Clients
+    get:
+      consumes:
+      - application/json
+      description: Get detailed information of a specific client by their ID
+      parameters:
+      - description: Client ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/utils.Response'
+      summary: Get client by ID
+      tags:
+      - Clients
+    put:
+      consumes:
+      - multipart/form-data
+      description: Update client information by ID
+      parameters:
+      - description: Client ID
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Client name
+        in: formData
+        name: name
+        type: string
+      - description: Client code
+        in: formData
+        name: code
+        type: string
+      - description: Client logo (optional)
+        in: formData
+        name: logo
+        type: file
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/utils.Response'
+      summary: Update client
+      tags:
+      - Clients
+  /clients/{id}/assign-menus:
+    post:
+      consumes:
+      - application/json
+      description: Assign one or more menus to a client
+      parameters:
+      - description: Client ID
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Menu assignment data
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/dto.AssignMenusToClientRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/utils.Response'
+      summary: Assign menus to client
+      tags:
+      - Clients
+  /clients/{id}/remove-menus:
+    post:
+      consumes:
+      - application/json
+      description: Remove one or more menus from a client
+      parameters:
+      - description: Client ID
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Menu removal data
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/dto.RemoveMenusFromClientRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/utils.Response'
+      summary: Remove menus from client
+      tags:
+      - Clients
   /example/helloworld:
     get:
       consumes:
@@ -222,6 +610,312 @@ paths:
       summary: ping example
       tags:
       - example
+  /maintenance-groups:
+    get:
+      consumes:
+      - application/json
+      description: Get all maintenance groups
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            items:
+              $ref: '#/definitions/utils.Response'
+            type: array
+        "400":
+          description: Bad Request
+          schema:
+            additionalProperties: true
+            type: object
+      summary: Get all maintenance groups
+      tags:
+      - MaintenanceGroup
+    post:
+      consumes:
+      - application/json
+      description: Create a new maintenance group
+      parameters:
+      - description: Create payload
+        in: body
+        name: body
+        required: true
+        schema:
+          $ref: '#/definitions/dto.MaintGroupCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            additionalProperties: true
+            type: object
+      summary: Create a new maintenance group
+      tags:
+      - MaintenanceGroup
+    put:
+      consumes:
+      - application/json
+      description: Update maintenance group
+      parameters:
+      - description: Update payload
+        in: body
+        name: body
+        required: true
+        schema:
+          $ref: '#/definitions/dto.MaintGroupUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            additionalProperties: true
+            type: object
+      summary: Update maintenance group
+      tags:
+      - MaintenanceGroup
+  /maintenance-groups/{id}:
+    delete:
+      consumes:
+      - application/json
+      description: Delete maintenance group
+      parameters:
+      - description: MaintenanceGroup ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+        "400":
+          description: Bad Request
+          schema:
+            additionalProperties: true
+            type: object
+      summary: Delete maintenance group
+      tags:
+      - MaintenanceGroup
+    get:
+      consumes:
+      - application/json
+      description: Get maintenance group by ID
+      parameters:
+      - description: MaintenanceGroup ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            additionalProperties: true
+            type: object
+      summary: Get maintenance group by ID
+      tags:
+      - MaintenanceGroup
+  /menus:
+    get:
+      consumes:
+      - application/json
+      description: Get paginated list of menus with filtering and sorting capabilities
+      parameters:
+      - description: Filter by name (partial match)
+        in: query
+        name: name
+        type: string
+      - description: Filter by parent menu ID
+        in: query
+        name: parent_id
+        type: string
+      - collectionFormat: csv
+        description: Include related entities
+        in: query
+        items:
+          type: string
+        name: includes
+        type: array
+      - description: 'Page number (default: 1)'
+        in: query
+        name: page
+        type: integer
+      - description: 'Page size (default: 10)'
+        in: query
+        name: page_size
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.ResponseWithPagination'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/utils.Response'
+      summary: Get list of menus
+      tags:
+      - Menus
+    post:
+      consumes:
+      - application/json
+      description: Create a new menu with the provided information
+      parameters:
+      - description: Menu creation data
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/dto.MenuCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/utils.Response'
+      summary: Create a new menu
+      tags:
+      - Menus
+  /menus/{id}:
+    delete:
+      consumes:
+      - application/json
+      description: Delete a menu by ID
+      parameters:
+      - description: Menu ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/utils.Response'
+      summary: Delete menu
+      tags:
+      - Menus
+    get:
+      consumes:
+      - application/json
+      description: Get detailed information of a specific menu by its ID
+      parameters:
+      - description: Menu ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/utils.Response'
+      summary: Get menu by ID
+      tags:
+      - Menus
+    put:
+      consumes:
+      - application/json
+      description: Update menu information by ID
+      parameters:
+      - description: Menu ID
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Menu update data
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/dto.MenuUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/utils.Response'
+      summary: Update menu
+      tags:
+      - Menus
+  /menus/by-name:
+    get:
+      consumes:
+      - application/json
+      description: Get menu information by its name
+      parameters:
+      - description: Menu name
+        in: query
+        name: name
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/utils.Response'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/utils.Response'
+      summary: Get menu by name
+      tags:
+      - Menus
   /users:
     delete:
       consumes:
@@ -274,7 +968,7 @@ paths:
           description: OK
           schema:
             items:
-              $ref: '#/definitions/dto.UserResponse'
+              $ref: '#/definitions/utils.ResponseWithPagination'
             type: array
         "400":
           description: Bad Request
@@ -304,7 +998,7 @@ paths:
         "200":
           description: OK
           schema:
-            $ref: '#/definitions/dto.UserResponse'
+            $ref: '#/definitions/utils.Response'
         "400":
           description: Bad Request
           schema:
@@ -332,7 +1026,7 @@ paths:
         "200":
           description: OK
           schema:
-            $ref: '#/definitions/dto.UserResponse'
+            $ref: '#/definitions/utils.Response'
         "400":
           description: Bad Request
           schema:
@@ -354,7 +1048,7 @@ paths:
         "200":
           description: OK
           schema:
-            $ref: '#/definitions/dto.UserResponse'
+            $ref: '#/definitions/utils.Response'
         "400":
           description: Bad Request
           schema:
@@ -384,7 +1078,7 @@ paths:
         "200":
           description: OK
           schema:
-            $ref: '#/definitions/dto.UserResponse'
+            $ref: '#/definitions/utils.Response'
         "400":
           description: Bad Request
           schema:
@@ -444,7 +1138,7 @@ paths:
         "200":
           description: OK
           schema:
-            $ref: '#/definitions/dto.UserResponse'
+            $ref: '#/definitions/utils.Response'
         "400":
           description: Bad Request
           schema:

modules/client/controller/client_controller.go

@@ -42,6 +42,19 @@ func NewClientController(i *do.Injector, clientService service.ClientService) Cl
 	}
 }
 
+// Create godoc
+// @Summary      Create a new client
+// @Description  Create a new client with the provided information
+// @Tags         Clients
+// @Accept       multipart/form-data
+// @Produce      json
+// @Param        name        formData  string  true   "Client name"
+// @Param        code        formData  string  true   "Client code"
+// @Param        logo        formData  file    false  "Client logo (optional)"
+// @Success      200  {object}  utils.Response
+// @Failure      400  {object}  utils.Response
+// @Failure      500  {object}  utils.Response
+// @Router       /clients [post]
 func (c *clientController) Create(ctx *gin.Context) {
 	var req dto.ClientCreateRequest
 	if err := ctx.ShouldBind(&req); err != nil {
@@ -69,6 +82,20 @@ func (c *clientController) Create(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, res)
 }
 
+// Update godoc
+// @Summary      Update client
+// @Description  Update client information by ID
+// @Tags         Clients
+// @Accept       multipart/form-data
+// @Produce      json
+// @Param        id          path      string  true   "Client ID"
+// @Param        name        formData  string  false  "Client name"
+// @Param        code        formData  string  false  "Client code"
+// @Param        logo        formData  file    false  "Client logo (optional)"
+// @Success      200  {object}  utils.Response
+// @Failure      400  {object}  utils.Response
+// @Failure      500  {object}  utils.Response
+// @Router       /clients/{id} [put]
 func (c *clientController) Update(ctx *gin.Context) {
 	id := ctx.Param("id")
 	var req dto.ClientUpdateRequest
@@ -97,6 +124,17 @@ func (c *clientController) Update(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, res)
 }
 
+// Delete godoc
+// @Summary      Delete client
+// @Description  Delete a client by ID
+// @Tags         Clients
+// @Accept       json
+// @Produce      json
+// @Param        id   path      string  true  "Client ID"
+// @Success      200  {object}  utils.Response
+// @Failure      400  {object}  utils.Response
+// @Failure      500  {object}  utils.Response
+// @Router       /clients/{id} [delete]
 func (c *clientController) Delete(ctx *gin.Context) {
 	id := ctx.Param("id")
 	if err := c.clientService.Delete(ctx, id); err != nil {
@@ -108,6 +146,17 @@ func (c *clientController) Delete(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, res)
 }
 
+// GetById godoc
+// @Summary      Get client by ID
+// @Description  Get detailed information of a specific client by their ID
+// @Tags         Clients
+// @Accept       json
+// @Produce      json
+// @Param        id   path      string  true  "Client ID"
+// @Success      200  {object}  utils.Response
+// @Failure      400  {object}  utils.Response
+// @Failure      404  {object}  utils.Response
+// @Router       /clients/{id} [get]
 func (c *clientController) GetById(ctx *gin.Context) {
 	id := ctx.Param("id")
 	client, err := c.clientService.GetById(ctx, id)
@@ -119,6 +168,20 @@ func (c *clientController) GetById(ctx *gin.Context) {
 	res := utils.BuildResponseSuccess(dto.MESSAGE_SUCCESS_GET_CLIENT, client)
 	ctx.JSON(http.StatusOK, res)
 }
+
+// GetAll godoc
+// @Summary      Get list of clients
+// @Description  Get paginated list of clients with filtering and sorting capabilities
+// @Tags         Clients
+// @Accept       json
+// @Produce      json
+// @Param        name      query     string  false  "Filter by name (partial match)"
+// @Param        code      query     string  false  "Filter by code (partial match)"
+// @Param        per_page  query     int     false  "Page size (default: 10)"
+// @Param        page      query     int     false  "Page number (default: 1)"
+// @Success      200  {object}  utils.ResponseWithPagination
+// @Failure      400  {object}  utils.Response
+// @Router       /clients [get]
 func (c *clientController) GetAll(ctx *gin.Context) {
 	// Ambil filter dari query param
 	var filter query.ClientFilter
@@ -146,7 +209,17 @@ func (c *clientController) GetAll(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, response)
 }
 
-// AssignMenusToClient implements MenuController.
+// AssignMenusToClient godoc
+// @Summary      Assign menus to client
+// @Description  Assign one or more menus to a client
+// @Tags         Clients
+// @Accept       json
+// @Produce      json
+// @Param        id      path      string  true  "Client ID"
+// @Param        request body dto.AssignMenusToClientRequest true "Menu assignment data"
+// @Success      200  {object}  utils.Response
+// @Failure      400  {object}  utils.Response
+// @Router       /clients/{id}/assign-menus [post]
 func (c *clientController) AssignMenusToClient(ctx *gin.Context) {
 	clientId := ctx.Param("id")
 	var req dto.AssignMenusToClientRequest
@@ -166,7 +239,17 @@ func (c *clientController) AssignMenusToClient(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, resp)
 }
 
-// RemoveMenusFromClient implements MenuController.
+// RemoveMenusFromClient godoc
+// @Summary      Remove menus from client
+// @Description  Remove one or more menus from a client
+// @Tags         Clients
+// @Accept       json
+// @Produce      json
+// @Param        id      path      string  true  "Client ID"
+// @Param        request body dto.RemoveMenusFromClientRequest true "Menu removal data"
+// @Success      200  {object}  utils.Response
+// @Failure      400  {object}  utils.Response
+// @Router       /clients/{id}/remove-menus [post]
 func (c *clientController) RemoveMenusFromClient(ctx *gin.Context) {
 	clientId := ctx.Param("id")
 	var req dto.RemoveMenusFromClientRequest

modules/maintenance_group/controller/maintenance_group_controller.go

@@ -49,7 +49,7 @@ func NewMaintenanceGroupController(i *do.Injector, maintGroupService service.Mai
 // @Accept       json
 // @Produce      json
 // @Param        body  body      dto.MaintGroupCreateRequest  true  "Create payload"
-// @Success      200   {object}  dto.MaintGroupResponse
+// @Success      200   {object}  utils.Response
 // @Failure      400   {object}  map[string]interface{}
 // @Router       /maintenance-groups [post]
 func (c *maintenanceGroupController) Create(ctx *gin.Context) {
@@ -78,7 +78,7 @@ func (c *maintenanceGroupController) Create(ctx *gin.Context) {
 // @Accept       json
 // @Produce      json
 // @Param        body  body      dto.MaintGroupUpdateRequest  true  "Update payload"
-// @Success      200   {object}  dto.MaintGroupResponse
+// @Success      200   {object}  utils.Response
 // @Failure      400   {object}  map[string]interface{}
 // @Router       /maintenance-groups [put]
 func (c *maintenanceGroupController) Update(ctx *gin.Context) {
@@ -127,7 +127,7 @@ func (c *maintenanceGroupController) Delete(ctx *gin.Context) {
 // @Accept       json
 // @Produce      json
 // @Param        id   path      string  true  "MaintenanceGroup ID"
-// @Success      200   {object}  dto.MaintGroupResponse
+// @Success      200   {object}  utils.Response
 // @Failure      400   {object}  map[string]interface{}
 // @Router       /maintenance-groups/{id} [get]
 func (c *maintenanceGroupController) GetById(ctx *gin.Context) {
@@ -148,7 +148,7 @@ func (c *maintenanceGroupController) GetById(ctx *gin.Context) {
 // @Tags         MaintenanceGroup
 // @Accept       json
 // @Produce      json
-// @Success      200   {array}   dto.MaintGroupResponse
+// @Success      200   {array}   utils.Response
 // @Failure      400   {object}  map[string]interface{}
 // @Router       /maintenance-groups [get]
 func (c *maintenanceGroupController) GetAll(ctx *gin.Context) {

modules/menu/controller/menu_controller.go

@@ -31,7 +31,16 @@ type (
 	}
 )
 
-// CreateMenu implements MenuController.
+// CreateMenu godoc
+// @Summary      Create a new menu
+// @Description  Create a new menu with the provided information
+// @Tags         Menus
+// @Accept       json
+// @Produce      json
+// @Param        request body dto.MenuCreateRequest true "Menu creation data"
+// @Success      200  {object}  utils.Response
+// @Failure      400  {object}  utils.Response
+// @Router       /menus [post]
 func (m *menuController) CreateMenu(ctx *gin.Context) {
 	var req dto.MenuCreateRequest
 	if err := ctx.ShouldBind(&req); err != nil {
@@ -63,7 +72,20 @@ func (m *menuController) CreateMenu(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, resp)
 }
 
-// GetMenus implements MenuController.
+// GetMenus godoc
+// @Summary      Get list of menus
+// @Description  Get paginated list of menus with filtering and sorting capabilities
+// @Tags         Menus
+// @Accept       json
+// @Produce      json
+// @Param        name      query     string  false  "Filter by name (partial match)"
+// @Param        parent_id query     string  false  "Filter by parent menu ID"
+// @Param        includes  query     []string false "Include related entities"
+// @Param        page      query     int     false  "Page number (default: 1)"
+// @Param        page_size query     int     false  "Page size (default: 10)"
+// @Success      200  {object}  utils.ResponseWithPagination
+// @Failure      400  {object}  utils.Response
+// @Router       /menus [get]
 func (m *menuController) GetMenus(ctx *gin.Context) {
 	_ = ctx.MustGet("client_id").(string)
 	var filter = &query.MenuFilter{
@@ -87,7 +109,17 @@ func (m *menuController) GetMenus(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, response)
 }
 
-// GetMenuByID implements MenuController.
+// GetMenuByID godoc
+// @Summary      Get menu by ID
+// @Description  Get detailed information of a specific menu by its ID
+// @Tags         Menus
+// @Accept       json
+// @Produce      json
+// @Param        id   path      string  true  "Menu ID"
+// @Success      200  {object}  utils.Response
+// @Failure      400  {object}  utils.Response
+// @Failure      404  {object}  utils.Response
+// @Router       /menus/{id} [get]
 func (m *menuController) GetMenuByID(ctx *gin.Context) {
 	id := ctx.Param("id")
 	if id == "" {
@@ -107,7 +139,16 @@ func (m *menuController) GetMenuByID(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, resp)
 }
 
-// GetMenuByName implements MenuController.
+// GetMenuByName godoc
+// @Summary      Get menu by name
+// @Description  Get menu information by its name
+// @Tags         Menus
+// @Accept       json
+// @Produce      json
+// @Param        name   query     string  true  "Menu name"
+// @Success      200  {object}  utils.Response
+// @Failure      400  {object}  utils.Response
+// @Router       /menus/by-name [get]
 func (m *menuController) GetMenuByName(ctx *gin.Context) {
 	name := ctx.Query("name")
 	if name == "" {
@@ -127,7 +168,17 @@ func (m *menuController) GetMenuByName(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, resp)
 }
 
-// UpdateMenu implements MenuController.
+// UpdateMenu godoc
+// @Summary      Update menu
+// @Description  Update menu information by ID
+// @Tags         Menus
+// @Accept       json
+// @Produce      json
+// @Param        id      path      string  true  "Menu ID"
+// @Param        request body dto.MenuUpdateRequest true "Menu update data"
+// @Success      200  {object}  utils.Response
+// @Failure      400  {object}  utils.Response
+// @Router       /menus/{id} [put]
 func (m *menuController) UpdateMenu(ctx *gin.Context) {
 	var req dto.MenuUpdateRequest
 	if err := ctx.ShouldBind(&req); err != nil {
@@ -148,7 +199,17 @@ func (m *menuController) UpdateMenu(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, resp)
 }
 
-// DeleteMenu implements MenuController.
+// DeleteMenu godoc
+// @Summary      Delete menu
+// @Description  Delete a menu by ID
+// @Tags         Menus
+// @Accept       json
+// @Produce      json
+// @Param        id   path      string  true  "Menu ID"
+// @Success      200  {object}  utils.Response
+// @Failure      400  {object}  utils.Response
+// @Failure      404  {object}  utils.Response
+// @Router       /menus/{id} [delete]
 func (m *menuController) DeleteMenu(ctx *gin.Context) {
 	id := ctx.Param("id")
 	if id == "" {

modules/user/controller/user_controller.go

@@ -51,7 +51,7 @@ func NewUserController(injector *do.Injector, us service.UserService) UserContro
 // @Accept       json
 // @Produce      json
 // @Param        body  body      dto.UserCreateRequest  true  "Register payload"
-// @Success      200   {object}  dto.UserResponse
+// @Success      200   {object}  utils.Response
 // @Failure      400   {object}  map[string]interface{}
 // @Failure      500   {object}  map[string]interface{}
 // @Router       /users/register [post]
@@ -85,7 +85,7 @@ func (c *userController) Register(ctx *gin.Context) {
 // @Param        page_size query     int     false  "Page size (default: 10)"
 // @Param        sort      query     string  false  "Sort expression, e.g. created_at desc"
 // @Security     ApiKeyAuth
-// @Success      200   {array}   dto.UserResponse
+// @Success      200   {array}   utils.ResponseWithPagination
 // @Failure      400   {object}  map[string]interface{}
 // @Router       /users [get]
 func (c *userController) GetAllUser(ctx *gin.Context) {
@@ -117,7 +117,7 @@ func (c *userController) GetAllUser(ctx *gin.Context) {
 // @Accept       json
 // @Produce      json
 // @Security     ApiKeyAuth
-// @Success      200   {object}  dto.UserResponse
+// @Success      200   {object}  utils.Response
 // @Failure      400   {object}  map[string]interface{}
 // @Router       /users/me [get]
 func (c *userController) Me(ctx *gin.Context) {
@@ -142,7 +142,7 @@ func (c *userController) Me(ctx *gin.Context) {
 // @Produce      json
 // @Param        id   path      string  true  "User ID"
 // @Security     ApiKeyAuth
-// @Success      200   {object}  dto.UserResponse
+// @Success      200   {object}  utils.Response
 // @Failure      400   {object}  map[string]interface{}
 // @Router       /users/{id} [get]
 func (c *userController) GetUserById(ctx *gin.Context) {
@@ -224,7 +224,7 @@ func (c *userController) SendVerificationEmail(ctx *gin.Context) {
 // @Accept       json
 // @Produce      json
 // @Param        body  body      dto.VerifyEmailRequest  true  "Verify email payload"
-// @Success      200   {object}  dto.UserResponse
+// @Success      200   {object}  utils.Response
 // @Failure      400   {object}  map[string]interface{}
 // @Router       /users/verify-email [post]
 func (c *userController) VerifyEmail(ctx *gin.Context) {
@@ -254,7 +254,7 @@ func (c *userController) VerifyEmail(ctx *gin.Context) {
 // @Produce      json
 // @Param        body  body      dto.UserUpdateRequest  true  "Update payload"
 // @Security     ApiKeyAuth
-// @Success      200   {object}  dto.UserResponse
+// @Success      200   {object}  utils.Response
 // @Failure      400   {object}  map[string]interface{}
 // @Router       /users [put]
 func (c *userController) Update(ctx *gin.Context) {