From 0daa884ed0af481d509e6bbd2c1602535fc341c8 Mon Sep 17 00:00:00 2001
From: Carlos Santos <4a.santos@gmail.com>
Date: Mon, 11 Aug 2025 11:55:05 +0200
Subject: [PATCH] backend: refactored update participant role functionality in
 meetings API and added openapi declaration

---
 .../internal/success-update-participant.yaml  |  9 +++++
 backend/openapi/paths/internal/meetings.yaml  | 39 +++++++++++++++++++
 .../src/controllers/participant.controller.ts |  4 +-
 backend/src/routes/meeting.routes.ts          |  2 +-
 backend/src/services/participant.service.ts   |  2 +-
 5 files changed, 52 insertions(+), 4 deletions(-)
 create mode 100644 backend/openapi/components/responses/internal/success-update-participant.yaml

diff --git a/backend/openapi/components/responses/internal/success-update-participant.yaml b/backend/openapi/components/responses/internal/success-update-participant.yaml
new file mode 100644
index 0000000..848401c
--- /dev/null
+++ b/backend/openapi/components/responses/internal/success-update-participant.yaml
@@ -0,0 +1,9 @@
+description: Successfully updated participant
+content:
+    application/json:
+        schema:
+            type: object
+            properties:
+                message:
+                    type: string
+                    example: 'Participant "123" role updated to "moderator"'
diff --git a/backend/openapi/paths/internal/meetings.yaml b/backend/openapi/paths/internal/meetings.yaml
index 3614c8f..bddff22 100644
--- a/backend/openapi/paths/internal/meetings.yaml
+++ b/backend/openapi/paths/internal/meetings.yaml
@@ -53,3 +53,42 @@
                 $ref: '../../components/responses/internal/error-room-participant-not-found.yaml'
             '500':
                 $ref: '../../components/responses/internal-server-error.yaml'
+    patch:
+        operationId: updateParticipant
+        summary: Update participant in a meeting
+        description: >
+            Updates the properties of a participant in the current meeting in an OpenVidu Meet room.
+            This can be used to change the participant role.
+        tags:
+            - Internal API - Meetings
+        security:
+            - participantTokenCookie: []
+        parameters:
+            - $ref: '../../components/parameters/room-id-path.yaml'
+            - $ref: '../../components/parameters/internal/participant-name.yaml'
+            # - $ref: '../../components/parameters/internal/x-participant-role.yaml'
+        requestBody:
+            required: true
+            content:
+                application/json:
+                    schema:
+                        type: object
+                        properties:
+                            role:
+                                type: string
+                                enum: [MODERATOR, SPEAKER]
+                                description: The new role for the participant.
+        responses:
+            '200':
+                $ref: '../../components/responses/internal/success-update-participant.yaml'
+            '400':
+                $ref: '../../components/responses/internal/error-invalid-participant-role.yaml'
+            '401':
+                $ref: '../../components/responses/unauthorized-error.yaml'
+            '403':
+                $ref: '../../components/responses/forbidden-error.yaml'
+            '404':
+                $ref: '../../components/responses/internal/error-room-participant-not-found.yaml'
+            '500':
+                $ref: '../../components/responses/internal-server-error.yaml'
+
diff --git a/backend/src/controllers/participant.controller.ts b/backend/src/controllers/participant.controller.ts
index 044c45f..ed917d2 100644
--- a/backend/src/controllers/participant.controller.ts
+++ b/backend/src/controllers/participant.controller.ts
@@ -133,7 +133,7 @@ export const deleteParticipant = async (req: Request, res: Response) => {
 	}
 };
 
-export const changeParticipantRole = async (req: Request, res: Response) => {
+export const updateParticipant = async (req: Request, res: Response) => {
 	const logger = container.get(LoggerService);
 	const participantService = container.get(ParticipantService);
 	const { roomId, participantName } = req.params;
@@ -141,7 +141,7 @@ export const changeParticipantRole = async (req: Request, res: Response) => {
 
 	try {
 		logger.verbose(`Changing role of participant '${participantName}' in room '${roomId}' to '${role}'`);
-		await participantService.changeParticipantRole(roomId, participantName, role);
+		await participantService.updateParticipantRole(roomId, participantName, role);
 		res.status(200).json({ message: `Participant '${participantName}' role updated to ${role}` });
 	} catch (error) {
 		handleError(res, error, `changing role for participant '${participantName}' in room '${roomId}'`);
diff --git a/backend/src/routes/meeting.routes.ts b/backend/src/routes/meeting.routes.ts
index 1dd32da..d4b894b 100644
--- a/backend/src/routes/meeting.routes.ts
+++ b/backend/src/routes/meeting.routes.ts
@@ -30,5 +30,5 @@ internalMeetingRouter.patch(
 	withModeratorPermissions,
 	withValidRoomId,
 	withValidParticipantRole,
-	participantCtrl.changeParticipantRole
+	participantCtrl.updateParticipant
 );
diff --git a/backend/src/services/participant.service.ts b/backend/src/services/participant.service.ts
index 317b2dd..13508bf 100644
--- a/backend/src/services/participant.service.ts
+++ b/backend/src/services/participant.service.ts
@@ -97,7 +97,7 @@ export class ParticipantService {
 		}
 	}
 
-	async changeParticipantRole(roomId: string, participantName: string, newRole: ParticipantRole): Promise<void> {
+	async updateParticipantRole(roomId: string, participantName: string, newRole: ParticipantRole): Promise<void> {
 		try {
 			const meetRoom = await this.roomService.getMeetRoom(roomId);