From d34f1238d15842e56decfe422fe4d194f462e111 Mon Sep 17 00:00:00 2001 From: Habib Fatkhul Rohman Date: Tue, 28 Oct 2025 15:25:59 +0700 Subject: [PATCH] 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/docs.go | 1141 ++++++++++++++++- docs/swagger.json | 1141 ++++++++++++++++- docs/swagger.yaml | 770 ++++++++++- .../client/controller/client_controller.go | 87 +- .../maintenance_group_controller.go | 8 +- modules/menu/controller/menu_controller.go | 73 +- modules/user/controller/user_controller.go | 12 +- 7 files changed, 3066 insertions(+), 166 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index 73a7fdf..192a4a6 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -115,6 +115,356 @@ const docTemplate = `{ } } }, + "/clients": { + "get": { + "description": "Get paginated list of clients with filtering and sorting capabilities", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Get list of clients", + "parameters": [ + { + "type": "string", + "description": "Filter by name (partial match)", + "name": "name", + "in": "query" + }, + { + "type": "string", + "description": "Filter by code (partial match)", + "name": "code", + "in": "query" + }, + { + "type": "integer", + "description": "Page size (default: 10)", + "name": "per_page", + "in": "query" + }, + { + "type": "integer", + "description": "Page number (default: 1)", + "name": "page", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.ResponseWithPagination" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + }, + "post": { + "description": "Create a new client with the provided information", + "consumes": [ + "multipart/form-data" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Create a new client", + "parameters": [ + { + "type": "string", + "description": "Client name", + "name": "name", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "Client code", + "name": "code", + "in": "formData", + "required": true + }, + { + "type": "file", + "description": "Client logo (optional)", + "name": "logo", + "in": "formData" + } + ], + "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" + } + } + } + } + }, + "/clients/{id}": { + "get": { + "description": "Get detailed information of a specific client by their ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Get client by ID", + "parameters": [ + { + "type": "string", + "description": "Client ID", + "name": "id", + "in": "path", + "required": true + } + ], + "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" + } + } + } + }, + "put": { + "description": "Update client information by ID", + "consumes": [ + "multipart/form-data" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Update client", + "parameters": [ + { + "type": "string", + "description": "Client ID", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "Client name", + "name": "name", + "in": "formData" + }, + { + "type": "string", + "description": "Client code", + "name": "code", + "in": "formData" + }, + { + "type": "file", + "description": "Client logo (optional)", + "name": "logo", + "in": "formData" + } + ], + "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" + } + } + } + }, + "delete": { + "description": "Delete a client by ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Delete client", + "parameters": [ + { + "type": "string", + "description": "Client ID", + "name": "id", + "in": "path", + "required": true + } + ], + "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" + } + } + } + } + }, + "/clients/{id}/assign-menus": { + "post": { + "description": "Assign one or more menus to a client", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Assign menus to client", + "parameters": [ + { + "type": "string", + "description": "Client ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Menu assignment data", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.AssignMenusToClientRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + } + }, + "/clients/{id}/remove-menus": { + "post": { + "description": "Remove one or more menus from a client", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Remove menus from client", + "parameters": [ + { + "type": "string", + "description": "Client ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Menu removal data", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.RemoveMenusFromClientRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + } + }, "/example/helloworld": { "get": { "description": "do ping", @@ -138,6 +488,466 @@ const docTemplate = `{ } } }, + "/maintenance-groups": { + "get": { + "description": "Get all maintenance groups", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "MaintenanceGroup" + ], + "summary": "Get all maintenance groups", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/utils.Response" + } + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "put": { + "description": "Update maintenance group", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "MaintenanceGroup" + ], + "summary": "Update maintenance group", + "parameters": [ + { + "description": "Update payload", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.MaintGroupUpdateRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "post": { + "description": "Create a new maintenance group", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "MaintenanceGroup" + ], + "summary": "Create a new maintenance group", + "parameters": [ + { + "description": "Create payload", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.MaintGroupCreateRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + } + }, + "/maintenance-groups/{id}": { + "get": { + "description": "Get maintenance group by ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "MaintenanceGroup" + ], + "summary": "Get maintenance group by ID", + "parameters": [ + { + "type": "string", + "description": "MaintenanceGroup ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "delete": { + "description": "Delete maintenance group", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "MaintenanceGroup" + ], + "summary": "Delete maintenance group", + "parameters": [ + { + "type": "string", + "description": "MaintenanceGroup ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object", + "additionalProperties": true + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + } + }, + "/menus": { + "get": { + "description": "Get paginated list of menus with filtering and sorting capabilities", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Menus" + ], + "summary": "Get list of menus", + "parameters": [ + { + "type": "string", + "description": "Filter by name (partial match)", + "name": "name", + "in": "query" + }, + { + "type": "string", + "description": "Filter by parent menu ID", + "name": "parent_id", + "in": "query" + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "csv", + "description": "Include related entities", + "name": "includes", + "in": "query" + }, + { + "type": "integer", + "description": "Page number (default: 1)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "Page size (default: 10)", + "name": "page_size", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.ResponseWithPagination" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + }, + "post": { + "description": "Create a new menu with the provided information", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Menus" + ], + "summary": "Create a new menu", + "parameters": [ + { + "description": "Menu creation data", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.MenuCreateRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + } + }, + "/menus/by-name": { + "get": { + "description": "Get menu information by its name", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Menus" + ], + "summary": "Get menu by name", + "parameters": [ + { + "type": "string", + "description": "Menu name", + "name": "name", + "in": "query", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + } + }, + "/menus/{id}": { + "get": { + "description": "Get detailed information of a specific menu by its ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Menus" + ], + "summary": "Get menu by ID", + "parameters": [ + { + "type": "string", + "description": "Menu ID", + "name": "id", + "in": "path", + "required": true + } + ], + "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" + } + } + } + }, + "put": { + "description": "Update menu information by ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Menus" + ], + "summary": "Update menu", + "parameters": [ + { + "type": "string", + "description": "Menu ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Menu update data", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.MenuUpdateRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + }, + "delete": { + "description": "Delete a menu by ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Menus" + ], + "summary": "Delete menu", + "parameters": [ + { + "type": "string", + "description": "Menu ID", + "name": "id", + "in": "path", + "required": true + } + ], + "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" + } + } + } + } + }, "/users": { "get": { "security": [ @@ -188,7 +998,7 @@ const docTemplate = `{ "schema": { "type": "array", "items": { - "$ref": "#/definitions/dto.UserResponse" + "$ref": "#/definitions/utils.ResponseWithPagination" } } }, @@ -233,7 +1043,7 @@ const docTemplate = `{ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.UserResponse" + "$ref": "#/definitions/utils.Response" } }, "400": { @@ -302,7 +1112,7 @@ const docTemplate = `{ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.UserResponse" + "$ref": "#/definitions/utils.Response" } }, "400": { @@ -343,7 +1153,7 @@ const docTemplate = `{ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.UserResponse" + "$ref": "#/definitions/utils.Response" } }, "400": { @@ -433,7 +1243,7 @@ const docTemplate = `{ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.UserResponse" + "$ref": "#/definitions/utils.Response" } }, "400": { @@ -477,7 +1287,7 @@ const docTemplate = `{ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.UserResponse" + "$ref": "#/definitions/utils.Response" } }, "400": { @@ -492,6 +1302,227 @@ const docTemplate = `{ } }, "definitions": { + "dto.AssignMenusToClientRequest": { + "type": "object", + "required": [ + "menu_ids" + ], + "properties": { + "menu_ids": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "dto.MaintGroupCreateRequest": { + "type": "object", + "required": [ + "client_id", + "code", + "maintenance_group_roles", + "name" + ], + "properties": { + "client_id": { + "type": "string" + }, + "code": { + "type": "string", + "maxLength": 50, + "minLength": 2 + }, + "description": { + "type": "string" + }, + "maintenance_group_roles": { + "type": "array", + "items": { + "$ref": "#/definitions/dto.MaintenanceGroupRole" + } + }, + "name": { + "type": "string", + "maxLength": 100, + "minLength": 2 + } + } + }, + "dto.MaintGroupUpdateRequest": { + "type": "object", + "properties": { + "client_id": { + "type": "string" + }, + "code": { + "type": "string", + "maxLength": 50, + "minLength": 2 + }, + "description": { + "type": "string" + }, + "maintenance_group_roles": { + "type": "array", + "items": { + "$ref": "#/definitions/dto.MaintenanceGroupRoleUpdate" + } + }, + "name": { + "type": "string", + "maxLength": 100, + "minLength": 2 + } + } + }, + "dto.MaintenanceGroupRole": { + "type": "object", + "required": [ + "level", + "maintenance_group_role_users", + "role_id" + ], + "properties": { + "level": { + "type": "integer" + }, + "maintenance_group_role_users": { + "type": "array", + "items": { + "$ref": "#/definitions/dto.MaintenanceGroupRoleUser" + } + }, + "role_id": { + "type": "string" + } + } + }, + "dto.MaintenanceGroupRoleUpdate": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "level": { + "type": "integer" + }, + "maintenance_group_role_users": { + "type": "array", + "items": { + "$ref": "#/definitions/dto.MaintenanceGroupRoleUser" + } + }, + "role_id": { + "type": "string" + } + } + }, + "dto.MaintenanceGroupRoleUser": { + "type": "object", + "required": [ + "user_id" + ], + "properties": { + "user_id": { + "type": "string" + } + } + }, + "dto.MenuCreateRequest": { + "type": "object", + "required": [ + "mode", + "name", + "sequence", + "url" + ], + "properties": { + "icon_url": { + "type": "string", + "maxLength": 100, + "minLength": 2 + }, + "mode": { + "type": "string", + "maxLength": 20, + "minLength": 8 + }, + "name": { + "type": "string", + "maxLength": 100, + "minLength": 2 + }, + "parent_id": { + "type": "string" + }, + "sequence": { + "type": "integer" + }, + "status": { + "type": "string" + }, + "table_name": { + "type": "string", + "maxLength": 10 + }, + "url": { + "type": "string", + "minLength": 8 + } + } + }, + "dto.MenuUpdateRequest": { + "type": "object", + "properties": { + "icon_url": { + "type": "string", + "maxLength": 100, + "minLength": 2 + }, + "mode": { + "type": "string", + "maxLength": 20, + "minLength": 2 + }, + "name": { + "type": "string", + "maxLength": 100, + "minLength": 2 + }, + "parent_id": { + "type": "string" + }, + "sequence": { + "type": "integer" + }, + "status": { + "type": "string" + }, + "table_name": { + "type": "string", + "maxLength": 10 + }, + "url": { + "type": "string", + "minLength": 8 + } + } + }, + "dto.RemoveMenusFromClientRequest": { + "type": "object", + "required": [ + "menu_ids" + ], + "properties": { + "menu_ids": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, "dto.SendVerificationEmailRequest": { "type": "object", "required": [ @@ -571,55 +1602,6 @@ const docTemplate = `{ } } }, - "dto.UserResponse": { - "type": "object", - "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": { - "type": "array", - "items": { - "$ref": "#/definitions/dto.UserRolesResponse" - } - }, - "username": { - "type": "string" - } - } - }, - "dto.UserRolesResponse": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - } - }, "dto.UserUpdateRequest": { "type": "object", "properties": { @@ -676,6 +1658,55 @@ const docTemplate = `{ "type": "string" } } + }, + "utils.PaginationResponse": { + "type": "object", + "properties": { + "max_page": { + "type": "integer" + }, + "page": { + "type": "integer" + }, + "per_page": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "utils.Response": { + "type": "object", + "properties": { + "data": {}, + "error": {}, + "message": { + "type": "string" + }, + "meta": {}, + "status": { + "type": "boolean" + } + } + }, + "utils.ResponseWithPagination": { + "type": "object", + "properties": { + "code": { + "type": "integer" + }, + "data": {}, + "message": { + "type": "string" + }, + "pagination": { + "$ref": "#/definitions/utils.PaginationResponse" + }, + "status": { + "type": "string" + } + } } }, "securityDefinitions": { diff --git a/docs/swagger.json b/docs/swagger.json index 4c7af97..d6c1779 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -109,6 +109,356 @@ } } }, + "/clients": { + "get": { + "description": "Get paginated list of clients with filtering and sorting capabilities", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Get list of clients", + "parameters": [ + { + "type": "string", + "description": "Filter by name (partial match)", + "name": "name", + "in": "query" + }, + { + "type": "string", + "description": "Filter by code (partial match)", + "name": "code", + "in": "query" + }, + { + "type": "integer", + "description": "Page size (default: 10)", + "name": "per_page", + "in": "query" + }, + { + "type": "integer", + "description": "Page number (default: 1)", + "name": "page", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.ResponseWithPagination" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + }, + "post": { + "description": "Create a new client with the provided information", + "consumes": [ + "multipart/form-data" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Create a new client", + "parameters": [ + { + "type": "string", + "description": "Client name", + "name": "name", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "Client code", + "name": "code", + "in": "formData", + "required": true + }, + { + "type": "file", + "description": "Client logo (optional)", + "name": "logo", + "in": "formData" + } + ], + "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" + } + } + } + } + }, + "/clients/{id}": { + "get": { + "description": "Get detailed information of a specific client by their ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Get client by ID", + "parameters": [ + { + "type": "string", + "description": "Client ID", + "name": "id", + "in": "path", + "required": true + } + ], + "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" + } + } + } + }, + "put": { + "description": "Update client information by ID", + "consumes": [ + "multipart/form-data" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Update client", + "parameters": [ + { + "type": "string", + "description": "Client ID", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "Client name", + "name": "name", + "in": "formData" + }, + { + "type": "string", + "description": "Client code", + "name": "code", + "in": "formData" + }, + { + "type": "file", + "description": "Client logo (optional)", + "name": "logo", + "in": "formData" + } + ], + "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" + } + } + } + }, + "delete": { + "description": "Delete a client by ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Delete client", + "parameters": [ + { + "type": "string", + "description": "Client ID", + "name": "id", + "in": "path", + "required": true + } + ], + "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" + } + } + } + } + }, + "/clients/{id}/assign-menus": { + "post": { + "description": "Assign one or more menus to a client", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Assign menus to client", + "parameters": [ + { + "type": "string", + "description": "Client ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Menu assignment data", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.AssignMenusToClientRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + } + }, + "/clients/{id}/remove-menus": { + "post": { + "description": "Remove one or more menus from a client", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Clients" + ], + "summary": "Remove menus from client", + "parameters": [ + { + "type": "string", + "description": "Client ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Menu removal data", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.RemoveMenusFromClientRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + } + }, "/example/helloworld": { "get": { "description": "do ping", @@ -132,6 +482,466 @@ } } }, + "/maintenance-groups": { + "get": { + "description": "Get all maintenance groups", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "MaintenanceGroup" + ], + "summary": "Get all maintenance groups", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/utils.Response" + } + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "put": { + "description": "Update maintenance group", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "MaintenanceGroup" + ], + "summary": "Update maintenance group", + "parameters": [ + { + "description": "Update payload", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.MaintGroupUpdateRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "post": { + "description": "Create a new maintenance group", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "MaintenanceGroup" + ], + "summary": "Create a new maintenance group", + "parameters": [ + { + "description": "Create payload", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.MaintGroupCreateRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + } + }, + "/maintenance-groups/{id}": { + "get": { + "description": "Get maintenance group by ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "MaintenanceGroup" + ], + "summary": "Get maintenance group by ID", + "parameters": [ + { + "type": "string", + "description": "MaintenanceGroup ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "delete": { + "description": "Delete maintenance group", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "MaintenanceGroup" + ], + "summary": "Delete maintenance group", + "parameters": [ + { + "type": "string", + "description": "MaintenanceGroup ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object", + "additionalProperties": true + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + } + }, + "/menus": { + "get": { + "description": "Get paginated list of menus with filtering and sorting capabilities", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Menus" + ], + "summary": "Get list of menus", + "parameters": [ + { + "type": "string", + "description": "Filter by name (partial match)", + "name": "name", + "in": "query" + }, + { + "type": "string", + "description": "Filter by parent menu ID", + "name": "parent_id", + "in": "query" + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "csv", + "description": "Include related entities", + "name": "includes", + "in": "query" + }, + { + "type": "integer", + "description": "Page number (default: 1)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "Page size (default: 10)", + "name": "page_size", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.ResponseWithPagination" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + }, + "post": { + "description": "Create a new menu with the provided information", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Menus" + ], + "summary": "Create a new menu", + "parameters": [ + { + "description": "Menu creation data", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.MenuCreateRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + } + }, + "/menus/by-name": { + "get": { + "description": "Get menu information by its name", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Menus" + ], + "summary": "Get menu by name", + "parameters": [ + { + "type": "string", + "description": "Menu name", + "name": "name", + "in": "query", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + } + }, + "/menus/{id}": { + "get": { + "description": "Get detailed information of a specific menu by its ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Menus" + ], + "summary": "Get menu by ID", + "parameters": [ + { + "type": "string", + "description": "Menu ID", + "name": "id", + "in": "path", + "required": true + } + ], + "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" + } + } + } + }, + "put": { + "description": "Update menu information by ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Menus" + ], + "summary": "Update menu", + "parameters": [ + { + "type": "string", + "description": "Menu ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Menu update data", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.MenuUpdateRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/utils.Response" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/utils.Response" + } + } + } + }, + "delete": { + "description": "Delete a menu by ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Menus" + ], + "summary": "Delete menu", + "parameters": [ + { + "type": "string", + "description": "Menu ID", + "name": "id", + "in": "path", + "required": true + } + ], + "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" + } + } + } + } + }, "/users": { "get": { "security": [ @@ -182,7 +992,7 @@ "schema": { "type": "array", "items": { - "$ref": "#/definitions/dto.UserResponse" + "$ref": "#/definitions/utils.ResponseWithPagination" } } }, @@ -227,7 +1037,7 @@ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.UserResponse" + "$ref": "#/definitions/utils.Response" } }, "400": { @@ -296,7 +1106,7 @@ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.UserResponse" + "$ref": "#/definitions/utils.Response" } }, "400": { @@ -337,7 +1147,7 @@ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.UserResponse" + "$ref": "#/definitions/utils.Response" } }, "400": { @@ -427,7 +1237,7 @@ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.UserResponse" + "$ref": "#/definitions/utils.Response" } }, "400": { @@ -471,7 +1281,7 @@ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.UserResponse" + "$ref": "#/definitions/utils.Response" } }, "400": { @@ -486,6 +1296,227 @@ } }, "definitions": { + "dto.AssignMenusToClientRequest": { + "type": "object", + "required": [ + "menu_ids" + ], + "properties": { + "menu_ids": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "dto.MaintGroupCreateRequest": { + "type": "object", + "required": [ + "client_id", + "code", + "maintenance_group_roles", + "name" + ], + "properties": { + "client_id": { + "type": "string" + }, + "code": { + "type": "string", + "maxLength": 50, + "minLength": 2 + }, + "description": { + "type": "string" + }, + "maintenance_group_roles": { + "type": "array", + "items": { + "$ref": "#/definitions/dto.MaintenanceGroupRole" + } + }, + "name": { + "type": "string", + "maxLength": 100, + "minLength": 2 + } + } + }, + "dto.MaintGroupUpdateRequest": { + "type": "object", + "properties": { + "client_id": { + "type": "string" + }, + "code": { + "type": "string", + "maxLength": 50, + "minLength": 2 + }, + "description": { + "type": "string" + }, + "maintenance_group_roles": { + "type": "array", + "items": { + "$ref": "#/definitions/dto.MaintenanceGroupRoleUpdate" + } + }, + "name": { + "type": "string", + "maxLength": 100, + "minLength": 2 + } + } + }, + "dto.MaintenanceGroupRole": { + "type": "object", + "required": [ + "level", + "maintenance_group_role_users", + "role_id" + ], + "properties": { + "level": { + "type": "integer" + }, + "maintenance_group_role_users": { + "type": "array", + "items": { + "$ref": "#/definitions/dto.MaintenanceGroupRoleUser" + } + }, + "role_id": { + "type": "string" + } + } + }, + "dto.MaintenanceGroupRoleUpdate": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "level": { + "type": "integer" + }, + "maintenance_group_role_users": { + "type": "array", + "items": { + "$ref": "#/definitions/dto.MaintenanceGroupRoleUser" + } + }, + "role_id": { + "type": "string" + } + } + }, + "dto.MaintenanceGroupRoleUser": { + "type": "object", + "required": [ + "user_id" + ], + "properties": { + "user_id": { + "type": "string" + } + } + }, + "dto.MenuCreateRequest": { + "type": "object", + "required": [ + "mode", + "name", + "sequence", + "url" + ], + "properties": { + "icon_url": { + "type": "string", + "maxLength": 100, + "minLength": 2 + }, + "mode": { + "type": "string", + "maxLength": 20, + "minLength": 8 + }, + "name": { + "type": "string", + "maxLength": 100, + "minLength": 2 + }, + "parent_id": { + "type": "string" + }, + "sequence": { + "type": "integer" + }, + "status": { + "type": "string" + }, + "table_name": { + "type": "string", + "maxLength": 10 + }, + "url": { + "type": "string", + "minLength": 8 + } + } + }, + "dto.MenuUpdateRequest": { + "type": "object", + "properties": { + "icon_url": { + "type": "string", + "maxLength": 100, + "minLength": 2 + }, + "mode": { + "type": "string", + "maxLength": 20, + "minLength": 2 + }, + "name": { + "type": "string", + "maxLength": 100, + "minLength": 2 + }, + "parent_id": { + "type": "string" + }, + "sequence": { + "type": "integer" + }, + "status": { + "type": "string" + }, + "table_name": { + "type": "string", + "maxLength": 10 + }, + "url": { + "type": "string", + "minLength": 8 + } + } + }, + "dto.RemoveMenusFromClientRequest": { + "type": "object", + "required": [ + "menu_ids" + ], + "properties": { + "menu_ids": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, "dto.SendVerificationEmailRequest": { "type": "object", "required": [ @@ -565,55 +1596,6 @@ } } }, - "dto.UserResponse": { - "type": "object", - "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": { - "type": "array", - "items": { - "$ref": "#/definitions/dto.UserRolesResponse" - } - }, - "username": { - "type": "string" - } - } - }, - "dto.UserRolesResponse": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - } - }, "dto.UserUpdateRequest": { "type": "object", "properties": { @@ -670,6 +1652,55 @@ "type": "string" } } + }, + "utils.PaginationResponse": { + "type": "object", + "properties": { + "max_page": { + "type": "integer" + }, + "page": { + "type": "integer" + }, + "per_page": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "utils.Response": { + "type": "object", + "properties": { + "data": {}, + "error": {}, + "message": { + "type": "string" + }, + "meta": {}, + "status": { + "type": "boolean" + } + } + }, + "utils.ResponseWithPagination": { + "type": "object", + "properties": { + "code": { + "type": "integer" + }, + "data": {}, + "message": { + "type": "string" + }, + "pagination": { + "$ref": "#/definitions/utils.PaginationResponse" + }, + "status": { + "type": "string" + } + } } }, "securityDefinitions": { diff --git a/docs/swagger.yaml b/docs/swagger.yaml index e5f907b..b5de1b4 100644 --- a/docs/swagger.yaml +++ b/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: diff --git a/modules/client/controller/client_controller.go b/modules/client/controller/client_controller.go index 3906858..6309cc1 100644 --- a/modules/client/controller/client_controller.go +++ b/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 diff --git a/modules/maintenance_group/controller/maintenance_group_controller.go b/modules/maintenance_group/controller/maintenance_group_controller.go index 8da6db1..a6e6b06 100644 --- a/modules/maintenance_group/controller/maintenance_group_controller.go +++ b/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) { diff --git a/modules/menu/controller/menu_controller.go b/modules/menu/controller/menu_controller.go index 6987323..fdd9d80 100644 --- a/modules/menu/controller/menu_controller.go +++ b/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 == "" { diff --git a/modules/user/controller/user_controller.go b/modules/user/controller/user_controller.go index 6b19d20..08c260e 100644 --- a/modules/user/controller/user_controller.go +++ b/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) {