diff --git a/README.md b/README.md index 573ac70..23cb53a 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,13 @@ base url: `http://localhost:3000` ### Department +- Get all Departments: `GET /api/departments/all` +- Create a Department: `POST /api/departments/create` +- Get a specific Department: `GET /api/departments/:id` +- Update a Department: `PUT /api/departments/:id` +- Soft Delete a Department: `DELETE /api/departments/:id` +- Restore a Department: `PATCH /api/departments/:id/restore` + ### Team - Create a new team in a specific organization: `POST /api/organization/:organizationId/department/:departmentId/team` diff --git a/src/docs/swagger.json b/src/docs/swagger.json index 143f239..f9415ad 100644 --- a/src/docs/swagger.json +++ b/src/docs/swagger.json @@ -1400,7 +1400,7 @@ } } }, - "/api/department/all": { + "/api/departments/all": { "get": { "tags": ["Department"], "summary": "Get all departments", @@ -1424,134 +1424,261 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "message": { - "type": "string", - "example": "Departments retrieved successfully" - }, - "currentPage": { - "type": "integer", - "example": 1 - }, - "totalPages": { - "type": "integer", - "example": 5 - }, - "totalDepartments": { - "type": "integer", - "example": 50 - }, - "departments": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid", - "example": "550e8400-e29b-41d4-a716-446655440000" - }, - "name": { - "type": "string", - "example": "Engineering" - }, - "organization": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - } - } - }, - "manager": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "firstName": { - "type": "string" - }, - "lastName": { - "type": "string" - } - } - }, - "teams": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - } - } - } - }, - "users": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "firstName": { - "type": "string" - }, - "lastName": { - "type": "string" - } - } - } - }, - "Report": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "title": { - "type": "string" - }, - "createdAt": { - "type": "string", - "format": "date-time" - } - } - } - } - } - } - } - } + "$ref": "#/components/schemas/GetAllDepartmentsResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" + } + } + } + }, + "/api/departments/create": { + "post": { + "tags": ["Department"], + "summary": "Create a new department", + "description": "Allows authorized users to create a new department.", + "operationId": "createDepartment", + "security": [{ "bearerAuth": [] }], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateDepartmentRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Department created successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateDepartmentResponse" + } + } + } }, - "403": { - "$ref": "#/components/responses/ForbiddenError" + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "409": { + "$ref": "#/components/responses/ConflictError" } } } }, + "/api/departments/{departmentId}": { + "get": { + "tags": ["Department"], + "summary": "Get department details", + "description": "Retrieve detailed information about a specific department.", + "operationId": "getDepartment", + "security": [{ "bearerAuth": [] }], + "parameters": [ + { + "name": "departmentId", + "in": "path", + "required": true, + "description": "ID of the department to retrieve", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/DepartmentDetailResponse" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + } + }, + "/api/departments/{departmentId}/update": { + "put": { + "tags": ["Department"], + "summary": "Update department details", + "description": "Update the details of a specific department.", + "operationId": "updateDepartment", + "security": [{ "bearerAuth": [] }], + "parameters": [ + { + "name": "departmentId", + "in": "path", + "required": true, + "description": "ID of the department to update", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "$ref": "#/components/requestBodies/UpdateDepartmentRequest" + }, + "responses": { + "200": { + "$ref": "#/components/responses/DepartmentDetailResponse" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + } + }, + "/api/departments/{id}": { + "get": { + "tags": ["Department"], + "summary": "Get department details", + "description": "Retrieve detailed information about a specific department.", + "operationId": "getDepartmentById", + "security": [{ "bearerAuth": [] }], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "ID of the department to retrieve", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Department details retrieved successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetDepartmentResponse" + } + } + } + }, + "404": { "$ref": "#/components/responses/NotFoundError" } + } + }, + "put": { + "tags": ["Department"], + "summary": "Update department details", + "description": "Update the details of a specific department.", + "operationId": "updateDepartment", + "security": [{ "bearerAuth": [] }], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "ID of the department to update", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateDepartmentRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Department updated successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateDepartmentResponse" + } + } + } + }, + "400": { "$ref": "#/components/responses/BadRequestError" }, + "404": { "$ref": "#/components/responses/NotFoundError" } + } + }, + "delete": { + "tags": ["Department"], + "summary": "Soft delete a department", + "description": "Mark a department as deleted.", + "operationId": "softDeleteDepartment", + "security": [{ "bearerAuth": [] }], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "ID of the department to delete", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Department soft deleted successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SoftDeleteDepartmentResponse" + } + } + } + }, + "404": { "$ref": "#/components/responses/NotFoundError" } + } + } + }, + "/api/departments/{id}/restore": { + "patch": { + "tags": ["Department"], + "summary": "Restore a soft-deleted department", + "description": "Restore a department that was previously soft-deleted.", + "operationId": "restoreDepartment", + "security": [{ "bearerAuth": [] }], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "ID of the department to restore", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Department restored successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RestoreDepartmentResponse" + } + } + } + }, + "404": { "$ref": "#/components/responses/NotFoundError" } + } + } + }, "/api/organization/{organizationId}/department/{departmentId}/team": { "post": { "tags": ["Team"], @@ -3863,479 +3990,6 @@ } } }, - "GetAllDepartmentsResponse": { - "type": "object", - "properties": { - "message": { - "type": "string", - "example": "Departments retrieved successfully" - }, - "currentPage": { - "type": "integer", - "example": 1 - }, - "totalPages": { - "type": "integer", - "example": 5 - }, - "totalDepartments": { - "type": "integer", - "example": 50 - }, - "departments": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid", - "example": "550e8400-e29b-41d4-a716-446655440000" - }, - "name": { - "type": "string", - "example": "Engineering" - }, - "organization": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - } - } - }, - "manager": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "firstName": { - "type": "string" - }, - "lastName": { - "type": "string" - } - } - }, - "teams": { - "type": "array", - "items": { - "CreateTeamRequest": { - "type": "object", - "required": ["name"], - "properties": { - "name": { - "type": "string", - "minLength": 2, - "maxLength": 100, - "example": "Frontend Team" - }, - "description": { - "type": "string", - "maxLength": 500, - "example": "Team responsible for frontend development" - }, - "avatar": { - "type": "string", - "format": "uri", - "example": "https://example.com/team-avatar.jpg" - }, - "members": { - "type": "array", - "items": { - "type": "object", - "required": ["userId"], - "properties": { - "userId": { - "type": "string", - "format": "uuid", - "example": "550e8400-e29b-41d4-a716-446655440001" - }, - "role": { - "type": "string", - "enum": ["LEADER", "MEMBER", "CONTRIBUTOR"], - "default": "MEMBER" - } - } - } - } - } - }, - "CreateTeamResponse": { - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - }, - "message": { - "type": "string", - "example": "Team created successfully" - }, - "data": { - "type": "object", - "properties": { - "team": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string" - } - } - }, - "teamLeader": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "leader": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - - "name": { - "type": "string" - } - } - } - }, - "users": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "firstName": { - "type": "string" - }, - "lastName": { - "userId": { - "type": "string", - "format": "uuid" - }, - "role": { - "type": "string" - } - } - } - }, - "Report": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "title": { - "type": "string" - }, - "createdAt": { - "type": "string", - "format": "date-time" - } - } - } - } - } - } - } - } - } - }, - "teamMembers": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "userId": { - "type": "string", - "format": "uuid" - }, - "role": { - "type": "string" - }, - "user": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - }, - "email": { - "type": "string" - }, - "avatar": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "TeamMember": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "userId": { - "type": "string", - "format": "uuid" - }, - "role": { - "type": "string", - "enum": ["LEADER", "MEMBER", "CONTRIBUTOR"] - }, - "isActive": { - "type": "boolean" - } - } - }, - "AddTeamMembersRequest": { - "type": "object", - "required": ["members"], - "properties": { - "members": { - "type": "array", - "minItems": 1, - "items": { - "type": "object", - "required": ["userId"], - "properties": { - "userId": { - "type": "string", - "format": "uuid", - "example": "550e8400-e29b-41d4-a716-446655440001" - }, - "role": { - "type": "string", - "enum": ["LEADER", "MEMBER", "CONTRIBUTOR"], - "default": "MEMBER" - } - } - } - } - } - }, - "AddTeamMembersResponse": { - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - }, - "message": { - "type": "string", - "example": "Members added successfully" - }, - "data": { - "type": "object", - "properties": { - "team": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string" - } - } - }, - "teamLeader": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - } - } - }, - "teamMembers": { - "type": "array", - "items": { - "$ref": "#/components/schemas/TeamMemberWithUser" - } - } - } - } - } - }, - "TeamMemberWithUser": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "userId": { - "type": "string", - "format": "uuid" - }, - "role": { - "type": "string", - "enum": ["LEADER", "MEMBER", "CONTRIBUTOR"] - }, - "user": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - }, - "email": { - "type": "string" - }, - "avatar": { - "type": "string", - "format": "uri", - "nullable": true - } - } - } - } - } - }, - "responses": { - "UnauthorizedError": { - "description": "Unauthorized", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "ValidationError": { - "description": "Validation error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "NotFoundError": { - "description": "Resource not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "ForbiddenError": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "InternalServerError": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - }, - "examples": { - "InvalidToken": { - "value": { - "success": false, - "message": "Invalid token" - } - }, - "ValidationError": { - "value": { - "success": false, - "message": "Validation failed", - "errors": [ - "\"email\" must be a valid email", - "\"password\" length must be at least 8 characters long" - ] - } - } - } - } - }, - "UpdateTeamRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 2, - "maxLength": 100, - "example": "Updated Team Name" - }, - "description": { - "type": "string", - "maxLength": 500, - "example": "Updated team description" - }, - "avatar": { - "type": "string", - "format": "uri", - "example": "https://example.com/new-team-avatar.jpg" - } - }, - "anyOf": [ - { "required": ["name"] }, - { "required": ["description"] }, - { "required": ["avatar"] } - ] - }, "UpdateTeamResponse": { "type": "object", "properties": { @@ -4851,6 +4505,126 @@ "type": "string" } } + }, + "CreateDepartmentRequest": { + "type": "object", + "properties": { + "name": { "type": "string", "example": "Engineering" }, + "description": { "type": "string", "example": "Handles engineering tasks" }, + "organizationId": { "type": "string", "format": "uuid" }, + "managerId": { "type": "string", "format": "uuid" } + }, + "required": ["name", "organizationId", "managerId"] + }, + "CreateDepartmentResponse": { + "type": "object", + "properties": { + "message": { "type": "string", "example": "Department created successfully" }, + "department": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "name": { "type": "string" }, + "description": { "type": "string" }, + "organizationId": { "type": "string", "format": "uuid" }, + "managerId": { "type": "string", "format": "uuid" } + } + } + } + }, + "GetAllDepartmentsResponse": { + "type": "object", + "properties": { + "message": { "type": "string", "example": "Departments retrieved successfully" }, + "departments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "name": { "type": "string" }, + "description": { "type": "string" }, + "organization": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "name": { "type": "string" } + } + }, + "manager": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "firstName": { "type": "string" }, + "lastName": { "type": "string" } + } + } + } + } + } + } + }, + "GetDepartmentResponse": { + "type": "object", + "properties": { + "message": { "type": "string", "example": "Department retrieved successfully" }, + "department": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "name": { "type": "string" }, + "description": { "type": "string" }, + "organization": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "name": { "type": "string" } + } + }, + "manager": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "firstName": { "type": "string" }, + "lastName": { "type": "string" } + } + } + } + } + } + }, + "UpdateDepartmentRequest": { + "type": "object", + "properties": { + "name": { "type": "string", "example": "Updated Department Name" }, + "description": { "type": "string", "example": "Updated description" } + } + }, + "UpdateDepartmentResponse": { + "type": "object", + "properties": { + "message": { "type": "string", "example": "Department updated successfully" }, + "department": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "name": { "type": "string" }, + "description": { "type": "string" } + } + } + } + }, + "SoftDeleteDepartmentResponse": { + "type": "object", + "properties": { + "message": { "type": "string", "example": "Department soft deleted successfully" } + } + }, + "RestoreDepartmentResponse": { + "type": "object", + "properties": { + "message": { "type": "string", "example": "Department restored successfully" } + } } } }