From 8cc81a9ff69184084be867513eae290030973a5a Mon Sep 17 00:00:00 2001 From: juancarmore Date: Mon, 14 Apr 2025 09:32:43 +0200 Subject: [PATCH] backend: Refactor OpenAPI specs for consistency and clarity, and fix some minor errors --- .../headers/set-cookie-access-token.yaml | 6 ++ .../headers/set-cookie-participant-token.yaml | 6 ++ .../headers/set-cookie-refresh-token.yaml | 6 ++ .../components/parameters/force-deletion.yaml | 9 +++ .../parameters/internal/participant-name.yaml | 3 +- .../parameters/internal/secret.yaml | 4 +- .../components/parameters/recording-id.yaml | 2 +- .../components/parameters/recording-ids.yaml | 7 ++ .../components/parameters/room-fields.yaml | 2 +- .../components/parameters/room-id.yaml | 2 +- .../components/parameters/room-ids.yaml | 7 ++ .../components/parameters/x-signature.yaml | 3 +- .../components/parameters/x-timestamp.yaml | 4 +- .../requestBodies/internal/login-user.yaml | 11 +--- .../internal/participant-token-request.yaml | 1 + .../{ => internal}/update-room-request.yaml | 2 +- .../start-recording-request.yaml | 6 +- .../responses/error-room-not-found.yaml | 4 +- .../error-participant-already-exists.yaml | 8 +++ .../internal/error-participant-not-found.yaml | 8 +++ .../error-participant-token-still-valid.yaml | 7 ++ .../error-recording-already-started.yaml | 2 +- .../internal/error-recording-not-active.yaml | 8 +++ .../internal/success-delete-participant.yaml | 9 +++ .../success-generate-participant-token.yaml | 13 ++++ .../internal/success-get-profile.yaml | 5 ++ .../internal/success-refresh-token.yaml | 7 +- .../success-start-recording.yaml | 4 +- .../success-stop-recording.yaml | 4 +- .../internal/success-update-room.yaml | 5 ++ .../internal/success-user-login.yaml | 14 +--- .../success-bulk-delete-recordings.yaml | 8 +-- .../responses/success-bulk-delete-rooms.yaml | 8 +-- .../responses/success-get-recordings.yaml | 2 +- .../responses/success-get-room.yaml | 8 +-- .../responses/success-get-rooms.yaml | 16 ++--- .../success-room-marked-for-deletion.yaml | 9 +++ backend/openapi/components/schemas/error.yaml | 2 +- .../schemas/internal/meet-token-options.yaml | 9 +-- .../schemas/internal/user-credentials.yaml | 13 ++++ .../components/schemas/internal/user.yaml | 10 +++ .../components/schemas/meet-recording.yaml | 11 ++-- .../components/schemas/meet-room-options.yaml | 4 +- .../schemas/meet-room-preferences.yaml | 20 ++---- .../openapi/components/schemas/meet-room.yaml | 11 ++-- .../components/schemas/meet-webhook.yaml | 10 +-- backend/openapi/components/security.yaml | 6 ++ backend/openapi/openvidu-meet-api.yaml | 2 +- .../openapi/openvidu-meet-internal-api.yaml | 63 +----------------- backend/openapi/paths/internal/auth.yaml | 38 ++++++----- .../openapi/paths/internal/participants.yaml | 66 +++---------------- .../openapi/paths/internal/recordings.yaml | 9 ++- backend/openapi/paths/internal/rooms.yaml | 14 +--- backend/openapi/paths/recordings.yaml | 12 +--- backend/openapi/paths/rooms.yaml | 36 +++++----- backend/openapi/webhooks/webhooks.yaml | 3 + 56 files changed, 275 insertions(+), 294 deletions(-) create mode 100644 backend/openapi/components/headers/set-cookie-access-token.yaml create mode 100644 backend/openapi/components/headers/set-cookie-participant-token.yaml create mode 100644 backend/openapi/components/headers/set-cookie-refresh-token.yaml create mode 100644 backend/openapi/components/parameters/force-deletion.yaml create mode 100644 backend/openapi/components/parameters/recording-ids.yaml create mode 100644 backend/openapi/components/parameters/room-ids.yaml rename backend/openapi/components/requestBodies/{ => internal}/update-room-request.yaml (93%) create mode 100644 backend/openapi/components/responses/internal/error-participant-already-exists.yaml create mode 100644 backend/openapi/components/responses/internal/error-participant-not-found.yaml create mode 100644 backend/openapi/components/responses/internal/error-participant-token-still-valid.yaml rename backend/openapi/components/responses/{ => internal}/error-recording-already-started.yaml (83%) create mode 100644 backend/openapi/components/responses/internal/error-recording-not-active.yaml create mode 100644 backend/openapi/components/responses/internal/success-delete-participant.yaml create mode 100644 backend/openapi/components/responses/internal/success-generate-participant-token.yaml create mode 100644 backend/openapi/components/responses/internal/success-get-profile.yaml rename backend/openapi/components/responses/{ => internal}/success-start-recording.yaml (73%) rename backend/openapi/components/responses/{ => internal}/success-stop-recording.yaml (86%) create mode 100644 backend/openapi/components/responses/internal/success-update-room.yaml create mode 100644 backend/openapi/components/responses/success-room-marked-for-deletion.yaml create mode 100644 backend/openapi/components/schemas/internal/user-credentials.yaml create mode 100644 backend/openapi/components/schemas/internal/user.yaml diff --git a/backend/openapi/components/headers/set-cookie-access-token.yaml b/backend/openapi/components/headers/set-cookie-access-token.yaml new file mode 100644 index 0000000..959a480 --- /dev/null +++ b/backend/openapi/components/headers/set-cookie-access-token.yaml @@ -0,0 +1,6 @@ +description: > + The cookie containing the access token. + This cookie is used to authenticate the user in subsequent requests. +schema: + type: string + example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict' diff --git a/backend/openapi/components/headers/set-cookie-participant-token.yaml b/backend/openapi/components/headers/set-cookie-participant-token.yaml new file mode 100644 index 0000000..efb0298 --- /dev/null +++ b/backend/openapi/components/headers/set-cookie-participant-token.yaml @@ -0,0 +1,6 @@ +description: > + The cookie containing the participant token. + This cookie is used to authenticate the participant in the room. +schema: + type: string + example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict' diff --git a/backend/openapi/components/headers/set-cookie-refresh-token.yaml b/backend/openapi/components/headers/set-cookie-refresh-token.yaml new file mode 100644 index 0000000..83df563 --- /dev/null +++ b/backend/openapi/components/headers/set-cookie-refresh-token.yaml @@ -0,0 +1,6 @@ +description: > + The cookie containing the refresh token. + This cookie is used to refresh the access token when it expires. +schema: + type: string + example: 'OvMeetRefreshToken=token_123456; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict' diff --git a/backend/openapi/components/parameters/force-deletion.yaml b/backend/openapi/components/parameters/force-deletion.yaml new file mode 100644 index 0000000..1e60a99 --- /dev/null +++ b/backend/openapi/components/parameters/force-deletion.yaml @@ -0,0 +1,9 @@ +name: force +in: query +description: > + Force deletion of the room even if there are active participants. + This will immediately disconnect all participants and remove the room. +required: false +schema: + type: string + example: 'true' diff --git a/backend/openapi/components/parameters/internal/participant-name.yaml b/backend/openapi/components/parameters/internal/participant-name.yaml index 3702f0b..e740a12 100644 --- a/backend/openapi/components/parameters/internal/participant-name.yaml +++ b/backend/openapi/components/parameters/internal/participant-name.yaml @@ -1,6 +1,7 @@ name: participantName in: path required: true -description: The name of the participant to delete +description: The name of the participant. schema: type: string + example: 'Alice' diff --git a/backend/openapi/components/parameters/internal/secret.yaml b/backend/openapi/components/parameters/internal/secret.yaml index 56615b2..fd7b778 100644 --- a/backend/openapi/components/parameters/internal/secret.yaml +++ b/backend/openapi/components/parameters/internal/secret.yaml @@ -1,6 +1,6 @@ name: secret -in: query +in: path required: true -description: The secret token from the room URL to check the participant's role +description: The secret value from the room URL used to connect to the room. schema: type: string diff --git a/backend/openapi/components/parameters/recording-id.yaml b/backend/openapi/components/parameters/recording-id.yaml index c3b0dcb..6a12b07 100644 --- a/backend/openapi/components/parameters/recording-id.yaml +++ b/backend/openapi/components/parameters/recording-id.yaml @@ -1,7 +1,7 @@ name: recordingId in: path required: true -description: The unique identifier of the recording to delete. +description: The unique identifier of the recording. schema: type: string example: 'room-123--EG_XYZ--XX445' diff --git a/backend/openapi/components/parameters/recording-ids.yaml b/backend/openapi/components/parameters/recording-ids.yaml new file mode 100644 index 0000000..4579362 --- /dev/null +++ b/backend/openapi/components/parameters/recording-ids.yaml @@ -0,0 +1,7 @@ +name: recordingIds +in: query +required: true +description: A comma-separated list of recording IDs to delete. +schema: + type: string + example: 'room-123--EG_XYZ--XX445,room-123--EG_ZYX--XX446' diff --git a/backend/openapi/components/parameters/room-fields.yaml b/backend/openapi/components/parameters/room-fields.yaml index 7483c8e..92d8668 100644 --- a/backend/openapi/components/parameters/room-fields.yaml +++ b/backend/openapi/components/parameters/room-fields.yaml @@ -6,4 +6,4 @@ description: > required: false schema: type: string - example: 'room-123' + example: 'roomId,moderatorRoomUrl' diff --git a/backend/openapi/components/parameters/room-id.yaml b/backend/openapi/components/parameters/room-id.yaml index 0e02feb..2f1de92 100644 --- a/backend/openapi/components/parameters/room-id.yaml +++ b/backend/openapi/components/parameters/room-id.yaml @@ -1,7 +1,7 @@ name: roomId in: path required: true -description: The unique identifier of the room to retrieve +description: The unique identifier of the room. schema: type: string example: 'room-123' diff --git a/backend/openapi/components/parameters/room-ids.yaml b/backend/openapi/components/parameters/room-ids.yaml new file mode 100644 index 0000000..fca8af8 --- /dev/null +++ b/backend/openapi/components/parameters/room-ids.yaml @@ -0,0 +1,7 @@ +name: roomIds +in: query +required: true +description: A comma-separated list of room IDs to delete. +schema: + type: string + example: 'room-123,room-456' diff --git a/backend/openapi/components/parameters/x-signature.yaml b/backend/openapi/components/parameters/x-signature.yaml index 7c1f4ec..0e19af8 100644 --- a/backend/openapi/components/parameters/x-signature.yaml +++ b/backend/openapi/components/parameters/x-signature.yaml @@ -1,6 +1,5 @@ name: X-Signature in: header -description: HMAC signature for webhook verification -example: 1234567890abcdef +description: HMAC signature for webhook verification. schema: type: string diff --git a/backend/openapi/components/parameters/x-timestamp.yaml b/backend/openapi/components/parameters/x-timestamp.yaml index 37668fd..2b84992 100644 --- a/backend/openapi/components/parameters/x-timestamp.yaml +++ b/backend/openapi/components/parameters/x-timestamp.yaml @@ -1,6 +1,6 @@ name: X-Timestamp in: header -description: Timestamp of the webhook event (in Unix Epoch seconds) -example: 1678901234 +description: Timestamp of the webhook event (in Unix Epoch milliseconds). schema: type: string + example: '1697030400000' diff --git a/backend/openapi/components/requestBodies/internal/login-user.yaml b/backend/openapi/components/requestBodies/internal/login-user.yaml index 0809a77..5147e08 100644 --- a/backend/openapi/components/requestBodies/internal/login-user.yaml +++ b/backend/openapi/components/requestBodies/internal/login-user.yaml @@ -3,13 +3,4 @@ required: true content: application/json: schema: - type: object - properties: - username: - type: string - example: 'admin' - description: The username of the user. - password: - type: string - example: 'password123' - description: The password of the user. + $ref: '../../schemas/internal/user-credentials.yaml' diff --git a/backend/openapi/components/requestBodies/internal/participant-token-request.yaml b/backend/openapi/components/requestBodies/internal/participant-token-request.yaml index 3e28ed9..cbdb434 100644 --- a/backend/openapi/components/requestBodies/internal/participant-token-request.yaml +++ b/backend/openapi/components/requestBodies/internal/participant-token-request.yaml @@ -1,4 +1,5 @@ description: Participant details +required: true content: application/json: schema: diff --git a/backend/openapi/components/requestBodies/update-room-request.yaml b/backend/openapi/components/requestBodies/internal/update-room-request.yaml similarity index 93% rename from backend/openapi/components/requestBodies/update-room-request.yaml rename to backend/openapi/components/requestBodies/internal/update-room-request.yaml index d93380b..77e628e 100644 --- a/backend/openapi/components/requestBodies/update-room-request.yaml +++ b/backend/openapi/components/requestBodies/internal/update-room-request.yaml @@ -2,7 +2,7 @@ description: Room update details content: application/json: schema: - $ref: '../schemas/meet-room-preferences.yaml#/MeetRoomPreferences' + $ref: '../../schemas/meet-room-preferences.yaml#/MeetRoomPreferences' examples: default: summary: Standard preferences diff --git a/backend/openapi/components/requestBodies/start-recording-request.yaml b/backend/openapi/components/requestBodies/start-recording-request.yaml index 7265847..504643f 100644 --- a/backend/openapi/components/requestBodies/start-recording-request.yaml +++ b/backend/openapi/components/requestBodies/start-recording-request.yaml @@ -1,13 +1,11 @@ description: Recording details +required: true content: application/json: schema: type: object - required: - - roomId properties: roomId: type: string + description: The unique identifier of the room to record. example: 'room-123' - description: > - The unique identifier of the room to record. \ No newline at end of file diff --git a/backend/openapi/components/responses/error-room-not-found.yaml b/backend/openapi/components/responses/error-room-not-found.yaml index c8dd91d..6265d1a 100644 --- a/backend/openapi/components/responses/error-room-not-found.yaml +++ b/backend/openapi/components/responses/error-room-not-found.yaml @@ -4,5 +4,5 @@ content: schema: $ref: '../schemas/error.yaml' example: - code: 404 - message: 'Room not found' + name: 'Room Error' + message: 'The room "room_123" does not exist' diff --git a/backend/openapi/components/responses/internal/error-participant-already-exists.yaml b/backend/openapi/components/responses/internal/error-participant-already-exists.yaml new file mode 100644 index 0000000..21f0155 --- /dev/null +++ b/backend/openapi/components/responses/internal/error-participant-already-exists.yaml @@ -0,0 +1,8 @@ +description: Conflict — The participant already exists in the room +content: + application/json: + schema: + $ref: '../../schemas/error.yaml' + example: + name: 'Participant Error' + message: '"Alice" already exists in the room "room_123"' diff --git a/backend/openapi/components/responses/internal/error-participant-not-found.yaml b/backend/openapi/components/responses/internal/error-participant-not-found.yaml new file mode 100644 index 0000000..45809d1 --- /dev/null +++ b/backend/openapi/components/responses/internal/error-participant-not-found.yaml @@ -0,0 +1,8 @@ +description: Participant not found +content: + application/json: + schema: + $ref: '../../schemas/error.yaml' + example: + name: 'Participant Error' + message: '"Alice" not found in room "room_123"' diff --git a/backend/openapi/components/responses/internal/error-participant-token-still-valid.yaml b/backend/openapi/components/responses/internal/error-participant-token-still-valid.yaml new file mode 100644 index 0000000..71c941e --- /dev/null +++ b/backend/openapi/components/responses/internal/error-participant-token-still-valid.yaml @@ -0,0 +1,7 @@ +description: Conflict — Current token is still valid +content: + application/json: + schema: + $ref: '../../schemas/error.yaml' + example: + message: 'Participant token is still valid' diff --git a/backend/openapi/components/responses/error-recording-already-started.yaml b/backend/openapi/components/responses/internal/error-recording-already-started.yaml similarity index 83% rename from backend/openapi/components/responses/error-recording-already-started.yaml rename to backend/openapi/components/responses/internal/error-recording-already-started.yaml index 18ab0b4..f7e9dca 100644 --- a/backend/openapi/components/responses/error-recording-already-started.yaml +++ b/backend/openapi/components/responses/internal/error-recording-already-started.yaml @@ -2,7 +2,7 @@ description: Conflict — The room is already being recorded content: application/json: schema: - $ref: '../schemas/error.yaml' + $ref: '../../schemas/error.yaml' example: name: 'Recording Error' message: 'The room "room-123" is already being recorded' diff --git a/backend/openapi/components/responses/internal/error-recording-not-active.yaml b/backend/openapi/components/responses/internal/error-recording-not-active.yaml new file mode 100644 index 0000000..8416c69 --- /dev/null +++ b/backend/openapi/components/responses/internal/error-recording-not-active.yaml @@ -0,0 +1,8 @@ +description: Conflict — The recording is in `STARTING` state or already stopped +content: + application/json: + schema: + $ref: '../../schemas/error.yaml' + example: + name: 'Recording Error' + message: 'Recording "room-123--EG_XYZ--XX445" is already stopped' diff --git a/backend/openapi/components/responses/internal/success-delete-participant.yaml b/backend/openapi/components/responses/internal/success-delete-participant.yaml new file mode 100644 index 0000000..f2a9577 --- /dev/null +++ b/backend/openapi/components/responses/internal/success-delete-participant.yaml @@ -0,0 +1,9 @@ +description: Successfully disconnect the participant +content: + application/json: + schema: + type: object + properties: + message: + type: string + example: 'Participant deleted' diff --git a/backend/openapi/components/responses/internal/success-generate-participant-token.yaml b/backend/openapi/components/responses/internal/success-generate-participant-token.yaml new file mode 100644 index 0000000..74b2eee --- /dev/null +++ b/backend/openapi/components/responses/internal/success-generate-participant-token.yaml @@ -0,0 +1,13 @@ +description: Successfully generated the participant token +headers: + Set-Cookie: + $ref: '../../headers/set-cookie-participant-token.yaml' +content: + application/json: + schema: + type: object + properties: + token: + type: string + description: > + The token to authenticate the participant. diff --git a/backend/openapi/components/responses/internal/success-get-profile.yaml b/backend/openapi/components/responses/internal/success-get-profile.yaml new file mode 100644 index 0000000..d35009b --- /dev/null +++ b/backend/openapi/components/responses/internal/success-get-profile.yaml @@ -0,0 +1,5 @@ +description: Successfully retrieved user profile +content: + application/json: + schema: + $ref: '../../schemas/internal/user.yaml' diff --git a/backend/openapi/components/responses/internal/success-refresh-token.yaml b/backend/openapi/components/responses/internal/success-refresh-token.yaml index 57a8c5c..8f9fb51 100644 --- a/backend/openapi/components/responses/internal/success-refresh-token.yaml +++ b/backend/openapi/components/responses/internal/success-refresh-token.yaml @@ -1,12 +1,7 @@ description: Successfully refreshed the access token headers: Set-Cookie: - description: > - The cookie containing the new access token. - This cookie is used to authenticate the user in subsequent requests. - schema: - type: string - example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict' + $ref: '../../headers/set-cookie-access-token.yaml' content: application/json: schema: diff --git a/backend/openapi/components/responses/success-start-recording.yaml b/backend/openapi/components/responses/internal/success-start-recording.yaml similarity index 73% rename from backend/openapi/components/responses/success-start-recording.yaml rename to backend/openapi/components/responses/internal/success-start-recording.yaml index b5410ff..70fd2c5 100644 --- a/backend/openapi/components/responses/success-start-recording.yaml +++ b/backend/openapi/components/responses/internal/success-start-recording.yaml @@ -2,10 +2,10 @@ description: Successfully created the OpenVidu Meet recording content: application/json: schema: - $ref: '../schemas/meet-recording.yaml' + $ref: '../../schemas/meet-recording.yaml' example: recordingId: 'room-123--EG_XYZ--XX445' roomId: 'room-123' status: 'STARTING' - filename: 'room-123--EG_XYZ--XX445' + filename: 'room-123--XX445.mp4' startDate: 1600000000000 diff --git a/backend/openapi/components/responses/success-stop-recording.yaml b/backend/openapi/components/responses/internal/success-stop-recording.yaml similarity index 86% rename from backend/openapi/components/responses/success-stop-recording.yaml rename to backend/openapi/components/responses/internal/success-stop-recording.yaml index a059c13..ce8242a 100644 --- a/backend/openapi/components/responses/success-stop-recording.yaml +++ b/backend/openapi/components/responses/internal/success-stop-recording.yaml @@ -8,12 +8,12 @@ headers: content: application/json: schema: - $ref: '../schemas/meet-recording.yaml' + $ref: '../../schemas/meet-recording.yaml' example: recordingId: 'room-123--EG_XYZ--XX445' roomId: 'room-123' status: 'ENDING' - filename: 'room-123--EG_XYZ--XX445' + filename: 'room-123--XX445.mp4' startDate: 1600000000000 duration: 3.6 details: 'End reason: StopEgress API' diff --git a/backend/openapi/components/responses/internal/success-update-room.yaml b/backend/openapi/components/responses/internal/success-update-room.yaml new file mode 100644 index 0000000..6d38ffc --- /dev/null +++ b/backend/openapi/components/responses/internal/success-update-room.yaml @@ -0,0 +1,5 @@ +description: Success response for updating a room +content: + application/json: + schema: + $ref: '../../schemas/meet-room.yaml' diff --git a/backend/openapi/components/responses/internal/success-user-login.yaml b/backend/openapi/components/responses/internal/success-user-login.yaml index b7767a5..ad06993 100644 --- a/backend/openapi/components/responses/internal/success-user-login.yaml +++ b/backend/openapi/components/responses/internal/success-user-login.yaml @@ -1,19 +1,9 @@ description: Successfully logged in headers: Set-Cookie: - description: > - The cookie containing the access token. - This cookie is used to authenticate the user in subsequent requests. - schema: - type: string - example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict' + $ref: '../../headers/set-cookie-access-token.yaml' Set-Cookie-Refresh: - description: > - The cookie containing the refresh token. - This cookie is used to refresh the access token when it expires. - schema: - type: string - example: 'OvMeetRefreshToken=token_123456; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict' + $ref: '../../headers/set-cookie-refresh-token.yaml' content: application/json: schema: diff --git a/backend/openapi/components/responses/success-bulk-delete-recordings.yaml b/backend/openapi/components/responses/success-bulk-delete-recordings.yaml index c04ebb6..16f4005 100644 --- a/backend/openapi/components/responses/success-bulk-delete-recordings.yaml +++ b/backend/openapi/components/responses/success-bulk-delete-recordings.yaml @@ -11,7 +11,7 @@ content: description: List of successfully deleted recording IDs. example: - 'room-123--EG_XYZ--XX445' - - 'room-123--EG_XYZ--XX446' + - 'room-123--EG_ZYX--XX446' notDeleted: type: array description: List of recordings that could not be deleted along with the corresponding error messages. @@ -32,7 +32,7 @@ content: value: deleted: - 'room-123--EG_XYZ--XX445' - - 'room-123--EG_XYZ--XX446' + - 'room-123--EG_ZYX--XX446' notDeleted: [] partial_deletion_with_errors: @@ -40,7 +40,7 @@ content: value: deleted: - 'room-123--EG_XYZ--XX445' - - 'room-123--EG_XYZ--XX446' + - 'room-123--EG_ZYX--XX446' notDeleted: - recordingId: 'room-123--EG_XYZ--XX447' error: 'Recording not found' @@ -54,5 +54,5 @@ content: notDeleted: - recordingId: 'room-123--EG_XYZ--XX445' error: 'Recording not found' - - recordingId: 'room-123--EG_XYZ--XX446' + - recordingId: 'room-123--EG_ZYX--XX446' error: 'Recording not found' diff --git a/backend/openapi/components/responses/success-bulk-delete-rooms.yaml b/backend/openapi/components/responses/success-bulk-delete-rooms.yaml index 3b3f74c..c0aed9e 100644 --- a/backend/openapi/components/responses/success-bulk-delete-rooms.yaml +++ b/backend/openapi/components/responses/success-bulk-delete-rooms.yaml @@ -14,12 +14,12 @@ content: - 'room-456' markedAsDeleted: type: array - description: List of rooms that were marked for deletion but not actually deleted. The rooms will be deleted when all participants leave the room. items: type: string - example: - - 'room-789' - - 'room-101' + description: List of rooms that were marked for deletion but not actually deleted. The rooms will be deleted when all participants leave the room. + example: + - 'room-789' + - 'room-101' examples: successful_deletion: summary: All rooms were successfully deleted diff --git a/backend/openapi/components/responses/success-get-recordings.yaml b/backend/openapi/components/responses/success-get-recordings.yaml index 05352b3..ed1a316 100644 --- a/backend/openapi/components/responses/success-get-recordings.yaml +++ b/backend/openapi/components/responses/success-get-recordings.yaml @@ -31,7 +31,7 @@ content: summary: A paginated response indicating more recordings are available value: recordings: - - recordingId: 'room-456--EG_XYZ--XX678' + - recordingId: 'room-456--EG_ZYX--XX678' roomId: 'room-456' status: 'COMPLETE' filename: 'room-456--XX678.mp4' diff --git a/backend/openapi/components/responses/success-get-room.yaml b/backend/openapi/components/responses/success-get-room.yaml index 921bda4..c5e4a67 100644 --- a/backend/openapi/components/responses/success-get-room.yaml +++ b/backend/openapi/components/responses/success-get-room.yaml @@ -18,8 +18,8 @@ content: enabled: false virtualBackgroundPreferences: enabled: true - moderatorURL: 'http://localhost:6080/room/room-123/?secret=tok_123456' - publisherURL: 'http://localhost:6080/room/room-123/?secret=tok_123456' + moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456' + publisherURL: 'http://localhost:6080/room/room-123/?secret=654321' roomId_fields_only: summary: Response with only the roomId @@ -44,5 +44,5 @@ content: urls_only: summary: Response containing only moderator and publisher URLs value: - moderatorURL: 'http://localhost:6080/room/room-123/?secret=tok_123456' - publisherURL: 'http://localhost:6080/room/room-123/?secret=tok_123456' + moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456' + publisherURL: 'http://localhost:6080/room/room-123/?secret=654321' diff --git a/backend/openapi/components/responses/success-get-rooms.yaml b/backend/openapi/components/responses/success-get-rooms.yaml index 655d9e8..2b3c1fe 100644 --- a/backend/openapi/components/responses/success-get-rooms.yaml +++ b/backend/openapi/components/responses/success-get-rooms.yaml @@ -39,8 +39,8 @@ content: enabled: false virtualBackgroundPreferences: enabled: true - moderatorURL: 'http://localhost:6080/room/room-123/?secret=tok_123456' - publisherURL: 'http://localhost:6080/room/room-123/?secret=tok_123456' + moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456' + publisherURL: 'http://localhost:6080/room/room-123/?secret=654321' - roomId: 'room-456' roomIdPrefix: 'room' creationDate: 1620001000000 @@ -52,8 +52,8 @@ content: enabled: true virtualBackgroundPreferences: enabled: false - moderatorURL: 'http://localhost:6080/room/room-456/?secret=tok_789012' - publisherURL: 'http://localhost:6080/room/room-456/?secret=tok_789012' + moderatorURL: 'http://localhost:6080/room/room-456/?secret=789012' + publisherURL: 'http://localhost:6080/room/room-456/?secret=210987' pagination: isTruncated: false maxItems: 10 @@ -102,10 +102,10 @@ content: summary: Response containing only moderator and publisher URLs value: rooms: - - moderatorURL: 'http://localhost:6080/room/room-123/?secret=tok_123456' - publisherURL: 'http://localhost:6080/room/room-123/?secret=tok_123456' - - moderatorURL: 'http://localhost:6080/room/room-456/?secret=tok_789012' - publisherURL: 'http://localhost:6080/room/room-456/?secret=tok_789012' + - moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456' + publisherURL: 'http://localhost:6080/room/room-123/?secret=654321' + - moderatorURL: 'http://localhost:6080/room/room-456/?secret=789012' + publisherURL: 'http://localhost:6080/room/room-456/?secret=210987' pagination: isTruncated: false maxItems: 10 diff --git a/backend/openapi/components/responses/success-room-marked-for-deletion.yaml b/backend/openapi/components/responses/success-room-marked-for-deletion.yaml new file mode 100644 index 0000000..26d2b8c --- /dev/null +++ b/backend/openapi/components/responses/success-room-marked-for-deletion.yaml @@ -0,0 +1,9 @@ +description: Room deletion accepted. The room will be deleted when all participants leave. +content: + application/json: + schema: + type: object + properties: + message: + type: string + example: 'Room marked for deletion' diff --git a/backend/openapi/components/schemas/error.yaml b/backend/openapi/components/schemas/error.yaml index 681fe78..553da84 100644 --- a/backend/openapi/components/schemas/error.yaml +++ b/backend/openapi/components/schemas/error.yaml @@ -8,4 +8,4 @@ properties: type: string code: type: integer -description: HTTP status code associated with the error + description: HTTP status code associated with the error diff --git a/backend/openapi/components/schemas/internal/meet-token-options.yaml b/backend/openapi/components/schemas/internal/meet-token-options.yaml index 683bae4..b364123 100644 --- a/backend/openapi/components/schemas/internal/meet-token-options.yaml +++ b/backend/openapi/components/schemas/internal/meet-token-options.yaml @@ -6,16 +6,13 @@ required: properties: roomId: type: string + description: The unique identifier of the room where the participant will join. example: 'room-123' - description: > - The ID of the room where the participant will join. participantName: type: string + description: The name of the participant. example: 'Alice' - description: > - The name of the participant. secret: type: string + description: The secret token from the room Url example: 'abc123456' - description: > - The secret token from the room Url diff --git a/backend/openapi/components/schemas/internal/user-credentials.yaml b/backend/openapi/components/schemas/internal/user-credentials.yaml new file mode 100644 index 0000000..6a12c2b --- /dev/null +++ b/backend/openapi/components/schemas/internal/user-credentials.yaml @@ -0,0 +1,13 @@ +type: object +required: + - username + - password +properties: + username: + type: string + description: The username of the user. + example: 'admin' + password: + type: string + description: The password of the user. + example: 'password123' \ No newline at end of file diff --git a/backend/openapi/components/schemas/internal/user.yaml b/backend/openapi/components/schemas/internal/user.yaml new file mode 100644 index 0000000..0623a92 --- /dev/null +++ b/backend/openapi/components/schemas/internal/user.yaml @@ -0,0 +1,10 @@ +type: object +properties: + username: + type: string + example: 'admin' + description: The username of the authenticated user. + role: + type: string + example: 'admin' + description: The role assigned to the authenticated user. diff --git a/backend/openapi/components/schemas/meet-recording.yaml b/backend/openapi/components/schemas/meet-recording.yaml index 0a9f957..0a99df2 100644 --- a/backend/openapi/components/schemas/meet-recording.yaml +++ b/backend/openapi/components/schemas/meet-recording.yaml @@ -7,7 +7,7 @@ properties: roomId: type: string example: 'room-123' - description: The ID of the room where the recording was made. + description: The unique identifier of the room where the recording was made. # outputMode: # type: string # example: 'COMPOSED' @@ -15,16 +15,13 @@ properties: # The output mode of the recording. Possible value: "COMPOSED". status: type: string - enum: ['STARTING', 'ACTIVE', 'ENDING', 'COMPLETE', 'FAILED', 'ABORTED', 'LIMITED_REACHED'] + enum: ['STARTING', 'ACTIVE', 'ENDING', 'COMPLETE', 'FAILED', 'ABORTED', 'LIMIT_REACHED'] example: 'ACTIVE' - description: > - The status of the recording. + description: The status of the recording. filename: type: string example: 'room-123--XX445.mp4' - description: > - The URL for the publisher to join the room. The publisher has permissions to publish audio and - video streams to the room. + description: The name of the recording file. startDate: type: [number, 'null'] example: 1620000000000 diff --git a/backend/openapi/components/schemas/meet-room-options.yaml b/backend/openapi/components/schemas/meet-room-options.yaml index dcf98d1..bf7603a 100644 --- a/backend/openapi/components/schemas/meet-room-options.yaml +++ b/backend/openapi/components/schemas/meet-room-options.yaml @@ -8,8 +8,8 @@ properties: After this date, the room will be automatically deleted and no new participants can join. - If this value is set, the room is marked for deletion but will only be removed after the last - participant leaves ("graceful deletion"). + If this value is set and the date has already passed, the room is marked for deletion but will only be removed after the last + participant leaves ("graceful deletion"). If this value is not defined, the room will exist indefinitely until manually deleted. roomIdPrefix: diff --git a/backend/openapi/components/schemas/meet-room-preferences.yaml b/backend/openapi/components/schemas/meet-room-preferences.yaml index d8f73c2..cc7d968 100644 --- a/backend/openapi/components/schemas/meet-room-preferences.yaml +++ b/backend/openapi/components/schemas/meet-room-preferences.yaml @@ -3,18 +3,13 @@ MeetRoomPreferences: properties: chatPreferences: $ref: '#/MeetChatPreferences' - description: > - Preferences for the chat feature in the room. - + description: Preferences for the chat feature in the room. recordingPreferences: $ref: '#/MeetRecordingPreferences' - description: > - Preferences for recording the room. - + description: Preferences for recording the room. virtualBackgroundPreferences: $ref: '#/MeetVirtualBackgroundPreferences' - description: > - Preferences for virtual background in the room. + description: Preferences for virtual background in the room. MeetChatPreferences: type: object @@ -23,8 +18,7 @@ MeetChatPreferences: type: boolean default: true example: true - description: > - If true, the room will be allowed to send and receive chat messages. + description: If true, the room will be allowed to send and receive chat messages. MeetRecordingPreferences: type: object properties: @@ -32,8 +26,7 @@ MeetRecordingPreferences: type: boolean default: true example: true - description: > - If true, the room will be allowed to record the video of the participants. + description: If true, the room will be allowed to record the video of the participants. MeetVirtualBackgroundPreferences: type: object properties: @@ -41,5 +34,4 @@ MeetVirtualBackgroundPreferences: type: boolean default: true example: true - description: > - If true, the room will be allowed to use virtual background. + description: If true, the room will be allowed to use virtual background. diff --git a/backend/openapi/components/schemas/meet-room.yaml b/backend/openapi/components/schemas/meet-room.yaml index 6fa1d09..3ed6e54 100644 --- a/backend/openapi/components/schemas/meet-room.yaml +++ b/backend/openapi/components/schemas/meet-room.yaml @@ -23,14 +23,13 @@ properties: After this date, the room will be automatically deleted and no new participants can join. - If this value is set, the room is marked for deletion but will only be removed after the last - participant leaves ("graceful deletion"). + If this value is set and the date has already passed, the room is marked for deletion but will only be removed after the last + participant leaves ("graceful deletion"). If this value is not defined, the room will exist indefinitely until manually deleted. preferences: $ref: meet-room-preferences.yaml#/MeetRoomPreferences - description: > - The preferences for the room. + description: The preferences for the room. # maxParticipants: # type: integer # example: 10 @@ -39,13 +38,13 @@ properties: # this limit, new participants will not be allowed to join. moderatorURL: type: string - example: 'http://localhost:6080/room/room-123/?secret=tok_123456' + example: 'http://localhost:6080/room/room-123/?secret=123456' description: > The URL for the moderator to join the room. The moderator has special permissions to manage the room and participants. publisherURL: type: string - example: 'http://localhost:6080/room/room-123/?secret=tok_123456' + example: 'http://localhost:6080/room/room-123/?secret=654321' description: > The URL for the publisher to join the room. The publisher has permissions to publish audio and video streams to the room. diff --git a/backend/openapi/components/schemas/meet-webhook.yaml b/backend/openapi/components/schemas/meet-webhook.yaml index a9aafee..53d313a 100644 --- a/backend/openapi/components/schemas/meet-webhook.yaml +++ b/backend/openapi/components/schemas/meet-webhook.yaml @@ -3,19 +3,19 @@ MeetWebhookEvent: properties: creationDate: type: number - description: 'The timestamp when the webhook event was created.' + description: The timestamp when the webhook event was created. event: $ref: '#/MeetWebhookEventType' - description: 'The type of event.' + description: The type of event. data: oneOf: - allOf: - title: Recording Event Data - - description: 'Data for recording-related events (started, updated, ended)' + - description: Data for recording-related events (started, updated, ended) - $ref: './meet-recording.yaml' # - allOf: # - title: Room Event Data - # - description: 'Data for room-related events (created, updated, deleted)' + # - description: Data for room-related events (created, updated, deleted) # - $ref: './meet-room.yaml' discriminator: propertyName: eventType @@ -26,7 +26,7 @@ MeetWebhookEvent: # roomCreated: './meet-room.yaml' # roomUpdated: './meet-room.yaml' # roomDeleted: './meet-room.yaml' - description: 'The event payload data, determined by the event type.' + description: The event payload data, determined by the event type. MeetWebhookEventType: type: string diff --git a/backend/openapi/components/security.yaml b/backend/openapi/components/security.yaml index 55710c0..456a855 100644 --- a/backend/openapi/components/security.yaml +++ b/backend/openapi/components/security.yaml @@ -10,6 +10,12 @@ accessTokenCookie: in: cookie description: > The JWT token to authenticate the request in case of consuming the API from the OpenVidu Meet frontend. +refreshTokenCookie: + type: apiKey + name: OvMeetRefreshToken + in: cookie + description: > + The JWT token to refresh the access token when it expires. This token is used to obtain a new access token. participantTokenCookie: type: apiKey name: OvMeetParticipantToken diff --git a/backend/openapi/openvidu-meet-api.yaml b/backend/openapi/openvidu-meet-api.yaml index 76c02b5..53ce3df 100644 --- a/backend/openapi/openvidu-meet-api.yaml +++ b/backend/openapi/openvidu-meet-api.yaml @@ -36,4 +36,4 @@ components: Error: $ref: components/schemas/error.yaml MeetWebhookEvent: - $ref: components/schemas/meet-webhook.yaml#/MeetWebhookEvent \ No newline at end of file + $ref: components/schemas/meet-webhook.yaml#/MeetWebhookEvent diff --git a/backend/openapi/openvidu-meet-internal-api.yaml b/backend/openapi/openvidu-meet-internal-api.yaml index 537c4f1..e2424bd 100644 --- a/backend/openapi/openvidu-meet-internal-api.yaml +++ b/backend/openapi/openvidu-meet-internal-api.yaml @@ -30,70 +30,13 @@ paths: $ref: './paths/internal/participants.yaml#/~1participants~1token~1refresh' /participants/{participantName}: $ref: './paths/internal/participants.yaml#/~1participants~1{participantName}' - delete: - operationId: disconnectParticipant - summary: Delete a participant from a room - description: > - Deletes a participant from an OpenVidu Meet room. - tags: - - Internal API - Participant - security: - - participantTokenCookie: [] - parameters: - - name: participantName - in: path - required: true - description: The name of the participant to delete - schema: - type: string - - name: roomId - in: query - required: true - description: The ID of the room where the participant is connected - schema: - type: string - responses: - '204': - description: Successfully disconnect the participant - '401': - description: Unauthorized — The participant access token is missing or invalid - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — The participant authenticated with the access token is not moderator of the room - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '404': - description: Participant not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 404 - message: 'Participant not found' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 500 - message: 'Internal server error' components: securitySchemes: $ref: './components/security.yaml' schemas: + User: + $ref: components/schemas/internal/user.yaml MeetRoom: $ref: components/schemas/meet-room.yaml MeetRoomOptions: @@ -104,5 +47,3 @@ components: $ref: components/schemas/meet-recording.yaml Error: $ref: components/schemas/error.yaml - MeetWebhookEvent: - $ref: components/schemas/meet-webhook.yaml#/MeetWebhookEvent diff --git a/backend/openapi/paths/internal/auth.yaml b/backend/openapi/paths/internal/auth.yaml index ec7181e..5ef97c7 100644 --- a/backend/openapi/paths/internal/auth.yaml +++ b/backend/openapi/paths/internal/auth.yaml @@ -11,7 +11,6 @@ responses: '200': $ref: '../../components/responses/internal/success-user-login.yaml' - # Should be 401 '404': $ref: '../../components/responses/internal/error-invalid-credentials.yaml' '422': @@ -28,8 +27,24 @@ - Internal API - Authentication responses: '200': - $ref: '../../components/responses/internal/success-user-logout.yaml' - + description: Successfully logged out + headers: + Set-Cookie: + schema: + type: string + example: 'OvMeetAccessToken=; Path=/; HttpOnly; SameSite=Strict' + Set-Cookie-Refresh: + schema: + type: string + example: 'OvMeetRefreshToken=; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict' + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: 'Logout successful' /auth/refresh: post: operationId: refreshAccessToken @@ -60,19 +75,6 @@ - accessTokenCookie: [] responses: '200': - description: Successfully retrieved user profile - content: - application/json: - schema: - type: object - properties: - username: - type: string - example: 'admin' - description: The username of the authenticated user. - role: - type: string - example: 'admin' - description: The role assigned to the authenticated user. + $ref: '../../components/responses/internal/success-get-profile.yaml' '401': - $ref: '../../components/responses/internal/error-invalid-refresh-token.yaml' + $ref: '../../components/responses/unauthorized-error.yaml' diff --git a/backend/openapi/paths/internal/participants.yaml b/backend/openapi/paths/internal/participants.yaml index bb4e0c1..c243add 100644 --- a/backend/openapi/paths/internal/participants.yaml +++ b/backend/openapi/paths/internal/participants.yaml @@ -12,41 +12,15 @@ $ref: '../../components/requestBodies/internal/participant-token-request.yaml' responses: '200': - description: Successfully generated the participant token - headers: - Set-Cookie: - description: > - The cookie containing the participant token. - This cookie is used to authenticate the participant in the room. - schema: - type: string - example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict' - content: - application/json: - schema: - type: object - properties: - token: - type: string - example: 'token_123456' - description: > - The token to authenticate the participant. + $ref: '../../components/responses/internal/success-generate-participant-token.yaml' '401': $ref: '../../components/responses/unauthorized-error.yaml' '403': $ref: '../../components/responses/forbidden-error.yaml' - '404': $ref: '../../components/responses/error-room-not-found.yaml' '409': - description: Conflict — The participant already exists in the room - content: - application/json: - schema: - $ref: '../../components/schemas/error.yaml' - example: - name: 'Participant Error' - message: 'Participant already exists in the room' + $ref: '../../components/responses/internal/error-participant-already-exists.yaml' '500': $ref: '../../components/responses/internal-server-error.yaml' @@ -64,25 +38,7 @@ $ref: '../../components/requestBodies/internal/participant-token-request.yaml' responses: '200': - description: Successfully refreshed the participant token - headers: - Set-Cookie: - description: > - The cookie containing the participant token. - This cookie is used to authenticate the participant in the room. - schema: - type: string - example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict' - content: - application/json: - schema: - type: object - properties: - token: - type: string - example: 'token_123456' - description: > - The token to authenticate the participant. + $ref: '../../components/responses/internal/success-generate-participant-token.yaml' '401': $ref: '../../components/responses/unauthorized-error.yaml' '403': @@ -90,13 +46,7 @@ '404': $ref: '../../components/responses/error-room-not-found.yaml' '409': - description: Conflict — Current token is still valid - content: - application/json: - schema: - $ref: '../../components/schemas/error.yaml' - example: - message: 'Participant token is still valid' + $ref: '../../components/responses/internal/error-participant-token-still-valid.yaml' '500': $ref: '../../components/responses/internal-server-error.yaml' /participants/{participantName}: @@ -110,16 +60,16 @@ security: - participantTokenCookie: [] parameters: - - $ref: '../../components/parameters/internal/participant-name.yaml' - $ref: '../../components/parameters/room-id.yaml' + - $ref: '../../components/parameters/internal/participant-name.yaml' responses: - '204': - description: Successfully disconnect the participant + '200': + $ref: '../../components/responses/internal/success-delete-participant.yaml' '401': $ref: '../../components/responses/unauthorized-error.yaml' '403': $ref: '../../components/responses/forbidden-error.yaml' '404': - $ref: '../../components/responses/error-room-not-found.yaml' + $ref: '../../components/responses/internal/error-participant-not-found.yaml' '500': $ref: '../../components/responses/internal-server-error.yaml' diff --git a/backend/openapi/paths/internal/recordings.yaml b/backend/openapi/paths/internal/recordings.yaml index aee2b19..f14d999 100644 --- a/backend/openapi/paths/internal/recordings.yaml +++ b/backend/openapi/paths/internal/recordings.yaml @@ -12,7 +12,7 @@ $ref: '../../components/requestBodies/start-recording-request.yaml' responses: '200': - $ref: '../../components/responses/success-start-recording.yaml' + $ref: '../../components/responses/internal/success-start-recording.yaml' '401': $ref: '../../components/responses/unauthorized-error.yaml' '403': @@ -20,12 +20,11 @@ '404': $ref: '../../components/responses/error-room-not-found.yaml' '409': - $ref: '../../components/responses/error-recording-already-started.yaml' + $ref: '../../components/responses/internal/error-recording-already-started.yaml' '422': $ref: '../../components/responses/validation-error.yaml' '500': $ref: '../../components/responses/internal-server-error.yaml' - /recordings/{recordingId}/stop: post: operationId: stopRecording @@ -41,7 +40,7 @@ - $ref: '../../components/parameters/recording-id.yaml' responses: '202': - $ref: '../../components/responses/success-stop-recording.yaml' + $ref: '../../components/responses/internal/success-stop-recording.yaml' '401': $ref: '../../components/responses/unauthorized-error.yaml' '403': @@ -49,7 +48,7 @@ '404': $ref: '../../components/responses/error-recording-not-found.yaml' '409': - $ref: '../../components/responses/error-recording-in-progress.yaml' + $ref: '../../components/responses/internal/error-recording-not-active.yaml' '500': $ref: '../../components/responses/internal-server-error.yaml' diff --git a/backend/openapi/paths/internal/rooms.yaml b/backend/openapi/paths/internal/rooms.yaml index f2dcc04..1a23060 100644 --- a/backend/openapi/paths/internal/rooms.yaml +++ b/backend/openapi/paths/internal/rooms.yaml @@ -7,21 +7,14 @@ tags: - Internal API - Rooms security: - - apiKeyInHeader: [] - accessTokenCookie: [] parameters: - - name: roomId - in: path - required: true - description: The unique identifier of the room to update - schema: - type: string - example: 'room-123' + - $ref: '../../components/parameters/room-id.yaml' requestBody: - $ref: '../../components/requestBodies/update-room-request.yaml' + $ref: '../../components/requestBodies/internal/update-room-request.yaml' responses: '200': - $ref: '../../components/responses/success-create-room.yaml' + $ref: '../../components/responses/internal/success-update-room.yaml' '401': $ref: '../../components/responses/unauthorized-error.yaml' '403': @@ -32,7 +25,6 @@ $ref: '../../components/responses/validation-error.yaml' '500': $ref: '../../components/responses/internal-server-error.yaml' - /rooms/{roomId}/participant-role: get: operationId: getParticipantRole diff --git a/backend/openapi/paths/recordings.yaml b/backend/openapi/paths/recordings.yaml index 92252fc..edd615d 100644 --- a/backend/openapi/paths/recordings.yaml +++ b/backend/openapi/paths/recordings.yaml @@ -56,14 +56,7 @@ - apiKeyInHeader: [] - accessTokenCookie: [] parameters: - - name: recordingIds - in: query - required: true - description: | - The unique IDs of the recordings to delete. - You can provide multiple recording IDs as a comma-separated list (e.g., `recordingIds=room-123--EG_XYZ--XX445,room-123--EG_XYZ--XX446`). - schema: - type: string + - $ref: '../components/parameters/recording-ids.yaml' responses: '200': $ref: '../components/responses/success-bulk-delete-recordings.yaml' @@ -138,7 +131,6 @@ tags: - OpenVidu Meet - Recordings security: - - apiKeyInHeader: [] - accessTokenCookie: [] parameters: - $ref: '../components/parameters/recording-id.yaml' @@ -194,7 +186,7 @@ '403': $ref: '../components/responses/forbidden-error.yaml' '404': - $ref: '../components/responses/error-room-not-found.yaml' + $ref: '../components/responses/error-recording-not-found.yaml' '416': description: Requested range not satisfiable content: diff --git a/backend/openapi/paths/rooms.yaml b/backend/openapi/paths/rooms.yaml index e54a0f5..9f0c697 100644 --- a/backend/openapi/paths/rooms.yaml +++ b/backend/openapi/paths/rooms.yaml @@ -53,22 +53,27 @@ summary: Bulk delete rooms description: > Delete multiple OpenVidu Meet rooms at once with the specified room IDs. + + If a room has active participants, it will be marked for deletion + and will be removed once all participants leave. + + If the "force" parameter is set to true, all rooms will be deleted immediately + regardless of active participants. tags: - OpenVidu Meet - Room security: - apiKeyInHeader: [] - accessTokenCookie: [] parameters: - - name: roomIds - in: query - required: true - description: A comma-separated list of room IDs to delete. - schema: - type: string - example: 'room-123,room-456' + - $ref: '../components/parameters/room-ids.yaml' + - $ref: '../components/parameters/force-deletion.yaml' responses: '200': $ref: '../components/responses/success-bulk-delete-rooms.yaml' + '202': + $ref: '../components/responses/success-room-marked-for-deletion.yaml' + '204': + description: Successfully deleted the OpenVidu Meet room '401': $ref: '../components/responses/unauthorized-error.yaml' '403': @@ -107,18 +112,13 @@ operationId: deleteRoom summary: Delete a room description: > - Permanently removes an OpenVidu Meet room with the specified room ID. - When a room is deleted: + Deletes an OpenVidu Meet room with the specified room ID. - - All active participants are immediately disconnected + If the room has active participants, it will be marked for deletion + and will be removed once all participants leave. - - All associated resources and session data are removed - - - The room ID becomes available for reuse - - This operation is idempotent - deleting a non-existent room or - attempting to delete an already removed room will return a successful - response. + If the "force" parameter is set to true, the room will be deleted immediately + regardless of active participants. tags: - OpenVidu Meet - Room security: @@ -128,7 +128,7 @@ - $ref: '../components/parameters/room-id.yaml' responses: '202': - description: Room deletion accepted. The room will be deleted when all participants leave. + $ref: '../components/responses/success-room-marked-for-deletion.yaml' '204': description: Successfully deleted the OpenVidu Meet room '401': diff --git a/backend/openapi/webhooks/webhooks.yaml b/backend/openapi/webhooks/webhooks.yaml index d45e0bf..c65913a 100644 --- a/backend/openapi/webhooks/webhooks.yaml +++ b/backend/openapi/webhooks/webhooks.yaml @@ -10,6 +10,7 @@ recordingStarted: parameters: - $ref: ../components/parameters/x-timestamp.yaml - $ref: ../components/parameters/x-signature.yaml + # TODO: Use defined schema for request body requestBody: required: true content: @@ -60,6 +61,7 @@ recordingUpdated: parameters: - $ref: ../components/parameters/x-timestamp.yaml - $ref: ../components/parameters/x-signature.yaml + # TODO: Use defined schema for request body requestBody: required: true content: @@ -112,6 +114,7 @@ recordingEnded: parameters: - $ref: ../components/parameters/x-timestamp.yaml - $ref: ../components/parameters/x-signature.yaml + # TODO: Use defined schema for request body requestBody: required: true content: