From 4ca7f82d155d9a57c210260e616fdebe4e4d217f Mon Sep 17 00:00:00 2001 From: juancarmore Date: Mon, 21 Jul 2025 18:34:50 +0200 Subject: [PATCH] Refactor OpenAPI documentation for clarity and consistency --- .../components/headers/accept-ranges.yaml | 3 +- .../headers/set-cookie-access-token.yaml | 2 +- .../headers/set-cookie-participant-token.yaml | 2 +- .../headers/set-cookie-recording-token.yaml | 2 +- .../headers/set-cookie-refresh-token.yaml | 2 +- .../components/parameters/force-deletion.yaml | 3 +- .../parameters/internal/participant-name.yaml | 2 +- .../components/parameters/max-items.yaml | 2 +- .../parameters/next-page-token.yaml | 2 +- .../components/parameters/private-access.yaml | 6 +- .../parameters/recording-fields.yaml | 6 +- .../components/parameters/recording-id.yaml | 2 +- .../components/parameters/recording-ids.yaml | 5 +- .../parameters/recording-range.yaml | 15 +++-- .../parameters/recording-secret.yaml | 3 +- .../parameters/recording-status.yaml | 19 ++++++ .../components/parameters/room-fields.yaml | 6 +- .../components/parameters/room-id-path.yaml | 2 +- .../components/parameters/room-id-query.yaml | 6 +- .../components/parameters/room-ids.yaml | 6 +- .../components/parameters/x-signature.yaml | 1 - .../components/parameters/x-timestamp.yaml | 2 - .../requestBodies/create-room-request.yaml | 2 +- .../internal/start-recording-request.yaml | 2 +- .../internal/update-room-request.yaml | 2 +- .../internal/update-security-preferences.yaml | 2 +- .../internal/update-webhooks-preferences.yaml | 2 +- .../internal/error-recording-not-active.yaml | 2 +- .../internal/success-delete-participant.yaml | 2 +- .../internal/success-start-recording.yaml | 2 +- .../internal/success-stop-recording.yaml | 2 +- .../internal/success-user-login.yaml | 2 +- .../internal/success-user-logout.yaml | 8 +-- .../responses/pro-feature-error.yaml | 2 +- .../success-bulk-delete-recordings.yaml | 8 +-- .../responses/success-bulk-delete-rooms.yaml | 4 +- .../responses/success-create-room.yaml | 2 +- .../responses/success-get-recording-url.yaml | 6 +- .../responses/success-get-recording.yaml | 2 +- .../responses/success-get-room.yaml | 8 +-- .../responses/success-get-rooms.yaml | 16 ++--- .../success-rooms-marked-for-deletion.yaml | 2 +- .../responses/validation-error.yaml | 2 +- .../components/responses/webhook-success.yaml | 12 ++-- .../internal/meet-room-role-permissions.yaml | 5 +- .../internal/security-preferences.yaml | 10 ++- .../components/schemas/internal/user.yaml | 1 + .../internal/webhooks-preferences.yaml | 1 + .../components/schemas/meet-pagination.yaml | 8 +-- .../components/schemas/meet-room-options.yaml | 13 ++-- .../openapi/components/schemas/meet-room.yaml | 21 +++---- .../schemas/webhook-base-event.yaml | 28 ++++----- backend/openapi/components/security.yaml | 2 +- backend/openapi/openvidu-meet-api.yaml | 2 - backend/openapi/paths/internal/auth.yaml | 40 ++++-------- .../paths/internal/global-preferences.yaml | 2 +- backend/openapi/paths/internal/meetings.yaml | 8 +-- .../openapi/paths/internal/participants.yaml | 4 +- .../openapi/paths/internal/recordings.yaml | 5 +- backend/openapi/paths/internal/rooms.yaml | 3 +- backend/openapi/paths/recordings.yaml | 61 +++++++------------ backend/openapi/paths/rooms.yaml | 7 ++- backend/openapi/webhooks/webhooks.yaml | 13 ++-- 63 files changed, 212 insertions(+), 213 deletions(-) create mode 100644 backend/openapi/components/parameters/recording-status.yaml diff --git a/backend/openapi/components/headers/accept-ranges.yaml b/backend/openapi/components/headers/accept-ranges.yaml index 8b9b0120..a60be2d8 100644 --- a/backend/openapi/components/headers/accept-ranges.yaml +++ b/backend/openapi/components/headers/accept-ranges.yaml @@ -1,4 +1,5 @@ -description: Indicates that the server supports range requests for content retrieval +description: > + Specifies that the server allows clients to request specific ranges of content, enabling partial retrieval of resources. schema: type: string example: bytes diff --git a/backend/openapi/components/headers/set-cookie-access-token.yaml b/backend/openapi/components/headers/set-cookie-access-token.yaml index 959a4807..4afa3636 100644 --- a/backend/openapi/components/headers/set-cookie-access-token.yaml +++ b/backend/openapi/components/headers/set-cookie-access-token.yaml @@ -3,4 +3,4 @@ description: > This cookie is used to authenticate the user in subsequent requests. schema: type: string - example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict' +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 index efb02981..7b3ab7c0 100644 --- a/backend/openapi/components/headers/set-cookie-participant-token.yaml +++ b/backend/openapi/components/headers/set-cookie-participant-token.yaml @@ -3,4 +3,4 @@ description: > This cookie is used to authenticate the participant in the room. schema: type: string - example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict' +example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict' diff --git a/backend/openapi/components/headers/set-cookie-recording-token.yaml b/backend/openapi/components/headers/set-cookie-recording-token.yaml index 6592be10..65e236ae 100644 --- a/backend/openapi/components/headers/set-cookie-recording-token.yaml +++ b/backend/openapi/components/headers/set-cookie-recording-token.yaml @@ -3,4 +3,4 @@ description: > This cookie is used to access the recordings in a room. schema: type: string - example: 'OvMeetRecordingToken=token_123456; Path=/; HttpOnly; SameSite=Strict' +example: 'OvMeetRecordingToken=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 index 83df5639..fc19c5e7 100644 --- a/backend/openapi/components/headers/set-cookie-refresh-token.yaml +++ b/backend/openapi/components/headers/set-cookie-refresh-token.yaml @@ -3,4 +3,4 @@ description: > 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' +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 index 1e60a992..fc99fdc4 100644 --- a/backend/openapi/components/parameters/force-deletion.yaml +++ b/backend/openapi/components/parameters/force-deletion.yaml @@ -5,5 +5,4 @@ description: > This will immediately disconnect all participants and remove the room. required: false schema: - type: string - example: 'true' + type: boolean diff --git a/backend/openapi/components/parameters/internal/participant-name.yaml b/backend/openapi/components/parameters/internal/participant-name.yaml index e740a126..328867bb 100644 --- a/backend/openapi/components/parameters/internal/participant-name.yaml +++ b/backend/openapi/components/parameters/internal/participant-name.yaml @@ -4,4 +4,4 @@ required: true description: The name of the participant. schema: type: string - example: 'Alice' +example: 'Alice' diff --git a/backend/openapi/components/parameters/max-items.yaml b/backend/openapi/components/parameters/max-items.yaml index a26946b0..9208cb38 100644 --- a/backend/openapi/components/parameters/max-items.yaml +++ b/backend/openapi/components/parameters/max-items.yaml @@ -1,7 +1,7 @@ name: maxItems in: query required: false -description: The number of rooms per page (default is 10). Maximum is 100. +description: Specifies the maximum number of items to return per page. The default value is 10, and the maximum allowed is 100. schema: type: integer default: 10 diff --git a/backend/openapi/components/parameters/next-page-token.yaml b/backend/openapi/components/parameters/next-page-token.yaml index 18a096c7..ee302f41 100644 --- a/backend/openapi/components/parameters/next-page-token.yaml +++ b/backend/openapi/components/parameters/next-page-token.yaml @@ -1,6 +1,6 @@ name: nextPageToken in: query required: false -description: The token to retrieve the next page of elements. +description: A token used for pagination to fetch the next set of items in a multi-page response. schema: type: string diff --git a/backend/openapi/components/parameters/private-access.yaml b/backend/openapi/components/parameters/private-access.yaml index 804392b0..fad35205 100644 --- a/backend/openapi/components/parameters/private-access.yaml +++ b/backend/openapi/components/parameters/private-access.yaml @@ -1,8 +1,8 @@ name: privateAcess in: query description: > - Indicates whether the retrieved recording URL should be configured for private access, i.e., the URL will be accessible only to authenticated users. + Specifies if the recording URL should be restricted to private access, + meaning only authenticated users can view or download the recording. required: false schema: - type: string - example: 'true' + type: boolean diff --git a/backend/openapi/components/parameters/recording-fields.yaml b/backend/openapi/components/parameters/recording-fields.yaml index 438ab224..9540d5ce 100644 --- a/backend/openapi/components/parameters/recording-fields.yaml +++ b/backend/openapi/components/parameters/recording-fields.yaml @@ -1,9 +1,9 @@ name: fields in: query description: > - The fields to retrieve from the recording. - Comma-separated list of fields to include in the response. + Specifies which fields to include in the response for the recording resource. + Provide a comma-separated list of field names. required: false schema: type: string - example: 'recordingId,roomId' \ No newline at end of file +example: 'recordingId,roomId' diff --git a/backend/openapi/components/parameters/recording-id.yaml b/backend/openapi/components/parameters/recording-id.yaml index 6a12b074..883ea710 100644 --- a/backend/openapi/components/parameters/recording-id.yaml +++ b/backend/openapi/components/parameters/recording-id.yaml @@ -4,4 +4,4 @@ required: true description: The unique identifier of the recording. schema: type: string - example: 'room-123--EG_XYZ--XX445' +example: 'room-123--EG_XYZ--XX445' diff --git a/backend/openapi/components/parameters/recording-ids.yaml b/backend/openapi/components/parameters/recording-ids.yaml index 20ad5bb5..72ca2e30 100644 --- a/backend/openapi/components/parameters/recording-ids.yaml +++ b/backend/openapi/components/parameters/recording-ids.yaml @@ -3,9 +3,8 @@ in: query required: true description: > A comma-separated list of recording IDs. -
- Each recording ID should be in the format 'roomId--egressId--uid' + Each recording ID must follow the format: `{roomId}--{egressId}--{uid}`. schema: type: string - example: 'room-123--EG_XYZ--XX445,room-123--EG_ZYX--XX446' +example: 'room-123--EG_XYZ--XX445,room-123--EG_ZYX--XX446' diff --git a/backend/openapi/components/parameters/recording-range.yaml b/backend/openapi/components/parameters/recording-range.yaml index fd40c4cd..3babb7f7 100644 --- a/backend/openapi/components/parameters/recording-range.yaml +++ b/backend/openapi/components/parameters/recording-range.yaml @@ -1,11 +1,14 @@ name: Range in: header required: false -description: > - This endpoint accepts a `Range` header to specify the byte range of the recording file to be streamed. - The format of the `Range` header should be `bytes=start-end`, where `start` is required and `end` is optional. - For example, - - `bytes=0-1023` to request the first 1024 bytes of the file. - - `bytes=1000-` to request from byte 1000 to the end of the file. +description: | + This endpoint supports the `Range` header to request a specific byte range of the recording file. + Use the format `bytes=start-end`, where `start` is the starting byte (required) and `end` is the ending byte (optional). + + Examples: + - `bytes=0-1023`: Requests bytes 0 through 1023 (first 1024 bytes). + - `bytes=1000-`: Requests from byte 1000 to the end of the file. + + This allows efficient partial downloads and resume capabilities for large files. schema: type: string diff --git a/backend/openapi/components/parameters/recording-secret.yaml b/backend/openapi/components/parameters/recording-secret.yaml index 811b1159..00a86704 100644 --- a/backend/openapi/components/parameters/recording-secret.yaml +++ b/backend/openapi/components/parameters/recording-secret.yaml @@ -1,6 +1,7 @@ name: secret in: query required: false -description: The secret value used to access the recording when sharing a recording link. +description: > + Optional secret value that must be provided to access the recording via a shared link, enhancing security for shared recordings. schema: type: string diff --git a/backend/openapi/components/parameters/recording-status.yaml b/backend/openapi/components/parameters/recording-status.yaml new file mode 100644 index 00000000..ddd39b67 --- /dev/null +++ b/backend/openapi/components/parameters/recording-status.yaml @@ -0,0 +1,19 @@ +name: status +in: query +required: false +description: | + Filter recordings by their status. + + You can provide multiple statuses as a comma-separated list (e.g., `status=ACTIVE,FAILED`). + + > ⚠️ **Note:** Using this filter may impact performance for large datasets. +schema: + type: string + enum: + - STARTING + - ACTIVE + - ENDING + - COMPLETE + - FAILED + - ABORTED + - LIMIT_REACHED diff --git a/backend/openapi/components/parameters/room-fields.yaml b/backend/openapi/components/parameters/room-fields.yaml index 92d86688..3244bf9e 100644 --- a/backend/openapi/components/parameters/room-fields.yaml +++ b/backend/openapi/components/parameters/room-fields.yaml @@ -1,9 +1,9 @@ name: fields in: query description: > - The fields to retrieve from the room. - Comma-separated list of fields to include in the response. + Specifies which fields to include in the response for the room resource. + Provide a comma-separated list of field names. required: false schema: type: string - example: 'roomId,moderatorRoomUrl' +example: 'roomId,moderatorRoomUrl' diff --git a/backend/openapi/components/parameters/room-id-path.yaml b/backend/openapi/components/parameters/room-id-path.yaml index 2f1de927..58405e59 100644 --- a/backend/openapi/components/parameters/room-id-path.yaml +++ b/backend/openapi/components/parameters/room-id-path.yaml @@ -4,4 +4,4 @@ required: true description: The unique identifier of the room. schema: type: string - example: 'room-123' +example: 'room-123' diff --git a/backend/openapi/components/parameters/room-id-query.yaml b/backend/openapi/components/parameters/room-id-query.yaml index f110244c..c27c602f 100644 --- a/backend/openapi/components/parameters/room-id-query.yaml +++ b/backend/openapi/components/parameters/room-id-query.yaml @@ -1,7 +1,9 @@ name: roomId in: query required: false -description: The unique identifier of the room. Specify the room ID to filter recordings by their associated room. +description: > + The unique identifier for the room. + Use this parameter to filter recordings and retrieve only those associated with the specified room ID. schema: type: string - example: 'room-123' +example: 'room-123' diff --git a/backend/openapi/components/parameters/room-ids.yaml b/backend/openapi/components/parameters/room-ids.yaml index fca8af8c..2e32fad1 100644 --- a/backend/openapi/components/parameters/room-ids.yaml +++ b/backend/openapi/components/parameters/room-ids.yaml @@ -1,7 +1,9 @@ name: roomIds in: query required: true -description: A comma-separated list of room IDs to delete. +description: > + Comma-separated list of room IDs to delete. + Each ID should correspond to an existing room. schema: type: string - example: 'room-123,room-456' +example: 'room-123,room-456' diff --git a/backend/openapi/components/parameters/x-signature.yaml b/backend/openapi/components/parameters/x-signature.yaml index b935e289..899fe8ee 100644 --- a/backend/openapi/components/parameters/x-signature.yaml +++ b/backend/openapi/components/parameters/x-signature.yaml @@ -2,7 +2,6 @@ name: x-signature in: header description: > HMAC-SHA256 signature of the request body, created using your webhook secret. - Use this to verify the webhook came from OpenVidu Meet and wasn't tampered with. required: true schema: diff --git a/backend/openapi/components/parameters/x-timestamp.yaml b/backend/openapi/components/parameters/x-timestamp.yaml index 72088759..f183bcc1 100644 --- a/backend/openapi/components/parameters/x-timestamp.yaml +++ b/backend/openapi/components/parameters/x-timestamp.yaml @@ -2,9 +2,7 @@ name: x-timestamp in: header description: > Unix timestamp (in seconds) when the webhook was sent. - Can be used to validate webhook age and prevent replay attacks. required: true schema: type: string - example: '1697030400000' diff --git a/backend/openapi/components/requestBodies/create-room-request.yaml b/backend/openapi/components/requestBodies/create-room-request.yaml index 6ae8110a..12236bb0 100644 --- a/backend/openapi/components/requestBodies/create-room-request.yaml +++ b/backend/openapi/components/requestBodies/create-room-request.yaml @@ -1,4 +1,4 @@ -description: Room creation details +description: Room creation options required: true content: application/json: diff --git a/backend/openapi/components/requestBodies/internal/start-recording-request.yaml b/backend/openapi/components/requestBodies/internal/start-recording-request.yaml index 504643f7..204f3774 100644 --- a/backend/openapi/components/requestBodies/internal/start-recording-request.yaml +++ b/backend/openapi/components/requestBodies/internal/start-recording-request.yaml @@ -1,4 +1,4 @@ -description: Recording details +description: Room to record required: true content: application/json: diff --git a/backend/openapi/components/requestBodies/internal/update-room-request.yaml b/backend/openapi/components/requestBodies/internal/update-room-request.yaml index 77e628e6..2d7f424a 100644 --- a/backend/openapi/components/requestBodies/internal/update-room-request.yaml +++ b/backend/openapi/components/requestBodies/internal/update-room-request.yaml @@ -1,4 +1,4 @@ -description: Room update details +description: New room preferences content: application/json: schema: diff --git a/backend/openapi/components/requestBodies/internal/update-security-preferences.yaml b/backend/openapi/components/requestBodies/internal/update-security-preferences.yaml index 042c034d..572b973b 100644 --- a/backend/openapi/components/requestBodies/internal/update-security-preferences.yaml +++ b/backend/openapi/components/requestBodies/internal/update-security-preferences.yaml @@ -1,4 +1,4 @@ -description: Security preferences +description: New security preferences required: true content: application/json: diff --git a/backend/openapi/components/requestBodies/internal/update-webhooks-preferences.yaml b/backend/openapi/components/requestBodies/internal/update-webhooks-preferences.yaml index 365ee536..a656cc9c 100644 --- a/backend/openapi/components/requestBodies/internal/update-webhooks-preferences.yaml +++ b/backend/openapi/components/requestBodies/internal/update-webhooks-preferences.yaml @@ -1,4 +1,4 @@ -description: Webhooks preferences +description: New webhooks preferences required: true content: application/json: diff --git a/backend/openapi/components/responses/internal/error-recording-not-active.yaml b/backend/openapi/components/responses/internal/error-recording-not-active.yaml index 84018981..7d27e4b5 100644 --- a/backend/openapi/components/responses/internal/error-recording-not-active.yaml +++ b/backend/openapi/components/responses/internal/error-recording-not-active.yaml @@ -1,4 +1,4 @@ -description: Conflict — The recording is in `STARTING` state or already stopped +description: Conflict — The recording is starting or already stopped content: application/json: schema: diff --git a/backend/openapi/components/responses/internal/success-delete-participant.yaml b/backend/openapi/components/responses/internal/success-delete-participant.yaml index f2a9577e..833475ac 100644 --- a/backend/openapi/components/responses/internal/success-delete-participant.yaml +++ b/backend/openapi/components/responses/internal/success-delete-participant.yaml @@ -1,4 +1,4 @@ -description: Successfully disconnect the participant +description: Successfully disconnected the participant content: application/json: schema: diff --git a/backend/openapi/components/responses/internal/success-start-recording.yaml b/backend/openapi/components/responses/internal/success-start-recording.yaml index 9a92f79e..c5c60caf 100644 --- a/backend/openapi/components/responses/internal/success-start-recording.yaml +++ b/backend/openapi/components/responses/internal/success-start-recording.yaml @@ -15,4 +15,4 @@ headers: schema: type: string format: uri - example: https://your-api.com/meet/internal-api/v1/recordings/room-123--EG_XYZ--XX445 + example: https://your-api.com/internal-api/v1/recordings/room-123--EG_XYZ--XX445 diff --git a/backend/openapi/components/responses/internal/success-stop-recording.yaml b/backend/openapi/components/responses/internal/success-stop-recording.yaml index ce8242ae..21109a8e 100644 --- a/backend/openapi/components/responses/internal/success-stop-recording.yaml +++ b/backend/openapi/components/responses/internal/success-stop-recording.yaml @@ -4,7 +4,7 @@ headers: description: The URL to retrieve the recording details schema: type: string - example: 'https://openvidu.example.com/meet/api/v1/recordings/room-123--EG_XYZ--XX445' + example: 'https://openvidu.example.com/api/v1/recordings/room-123--EG_XYZ--XX445' content: application/json: schema: diff --git a/backend/openapi/components/responses/internal/success-user-login.yaml b/backend/openapi/components/responses/internal/success-user-login.yaml index ad06993b..57d6b6f2 100644 --- a/backend/openapi/components/responses/internal/success-user-login.yaml +++ b/backend/openapi/components/responses/internal/success-user-login.yaml @@ -2,7 +2,7 @@ description: Successfully logged in headers: Set-Cookie: $ref: '../../headers/set-cookie-access-token.yaml' - Set-Cookie-Refresh: + Set-Cookie*: $ref: '../../headers/set-cookie-refresh-token.yaml' content: application/json: diff --git a/backend/openapi/components/responses/internal/success-user-logout.yaml b/backend/openapi/components/responses/internal/success-user-logout.yaml index c2964f3a..d4ce0380 100644 --- a/backend/openapi/components/responses/internal/success-user-logout.yaml +++ b/backend/openapi/components/responses/internal/success-user-logout.yaml @@ -1,13 +1,11 @@ description: Successfully logged out headers: Set-Cookie: + description: > + Clears the access and refresh token 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' + example: 'OvMeetAccessToken=; Path=/; HttpOnly; SameSite=Strict' content: application/json: schema: diff --git a/backend/openapi/components/responses/pro-feature-error.yaml b/backend/openapi/components/responses/pro-feature-error.yaml index ad61839a..0757f1c9 100644 --- a/backend/openapi/components/responses/pro-feature-error.yaml +++ b/backend/openapi/components/responses/pro-feature-error.yaml @@ -1,4 +1,4 @@ -description: PRO Feature Error +description: PRO feature 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 1bfda264..a91abb37 100644 --- a/backend/openapi/components/responses/success-bulk-delete-recordings.yaml +++ b/backend/openapi/components/responses/success-bulk-delete-recordings.yaml @@ -36,14 +36,14 @@ content: - recordingId: 'room-123--EG_XYZ--XX447' error: 'Recording not found' - recordingId: 'room-123--EG_XYZ--XX448' - error: 'Access denied for deletion' + error: 'Recording in progress' no_deletion_performed: summary: No recordings were deleted value: deleted: [] notDeleted: - - recordingId: 'room-123--EG_XYZ--XX445' - error: 'Recording not found' - - recordingId: 'room-123--EG_ZYX--XX446' + - recordingId: 'room-123--EG_XYZ--XX447' error: 'Recording not found' + - recordingId: 'room-123--EG_ZYX--XX448' + error: 'Recording in progress' diff --git a/backend/openapi/components/responses/success-bulk-delete-rooms.yaml b/backend/openapi/components/responses/success-bulk-delete-rooms.yaml index e87609c6..8f263cd3 100644 --- a/backend/openapi/components/responses/success-bulk-delete-rooms.yaml +++ b/backend/openapi/components/responses/success-bulk-delete-rooms.yaml @@ -15,7 +15,9 @@ content: type: array items: type: string - description: List of rooms that were marked for deletion but not actually deleted. The rooms will be deleted when all participants leave the room. + description: >- + List of rooms that were marked for deletion but not actually deleted. + These rooms will be deleted when all participants leave. example: deleted: - 'room-123' diff --git a/backend/openapi/components/responses/success-create-room.yaml b/backend/openapi/components/responses/success-create-room.yaml index 3215f44c..d746f6c3 100644 --- a/backend/openapi/components/responses/success-create-room.yaml +++ b/backend/openapi/components/responses/success-create-room.yaml @@ -9,4 +9,4 @@ headers: schema: type: string format: uri - example: https://your-api.com/meet/api/v1/rooms/room-id-123 + example: https://your-api.com/api/v1/rooms/room-123 diff --git a/backend/openapi/components/responses/success-get-recording-url.yaml b/backend/openapi/components/responses/success-get-recording-url.yaml index 44940a27..4d11f5d8 100644 --- a/backend/openapi/components/responses/success-get-recording-url.yaml +++ b/backend/openapi/components/responses/success-get-recording-url.yaml @@ -1,4 +1,4 @@ -description: Successfully retrieved the recording URL. +description: Successfully retrieved the recording URL content: application/json: schema: @@ -7,5 +7,5 @@ content: url: type: string format: uri - description: URL to access the recording media. - example: https://example.com/meet/api/v1/recordings/room-123--EG_XYZ--XX445/media?secret=abc123 + description: URL to access the recording. + example: https://example.com/recording/room-123--EG_XYZ--XX445?secret=abc123 diff --git a/backend/openapi/components/responses/success-get-recording.yaml b/backend/openapi/components/responses/success-get-recording.yaml index fa28bda6..3c60337f 100644 --- a/backend/openapi/components/responses/success-get-recording.yaml +++ b/backend/openapi/components/responses/success-get-recording.yaml @@ -1,4 +1,4 @@ -description: Successfully retrieved the recording. +description: Successfully retrieved the recording content: application/json: schema: diff --git a/backend/openapi/components/responses/success-get-room.yaml b/backend/openapi/components/responses/success-get-room.yaml index 2e21f11c..f00fd5c2 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=123456' - publisherURL: 'http://localhost:6080/room/room-123/?secret=654321' + moderatorURL: 'http://localhost:6080/room/room-123?secret=123456' + publisherURL: 'http://localhost:6080/room/room-123?secret=654321' fields=roomId: summary: Response with only the roomId @@ -44,5 +44,5 @@ content: fields=moderatorURL,publisherURL: summary: Response containing only moderator and publisher URLs value: - moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456' - publisherURL: 'http://localhost:6080/room/room-123/?secret=654321' + 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 ff4276a0..c25be431 100644 --- a/backend/openapi/components/responses/success-get-rooms.yaml +++ b/backend/openapi/components/responses/success-get-rooms.yaml @@ -27,8 +27,8 @@ content: enabled: false virtualBackgroundPreferences: enabled: true - moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456' - publisherURL: 'http://localhost:6080/room/room-123/?secret=654321' + 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 @@ -40,8 +40,8 @@ content: enabled: true virtualBackgroundPreferences: enabled: false - moderatorURL: 'http://localhost:6080/room/room-456/?secret=789012' - publisherURL: 'http://localhost:6080/room/room-456/?secret=210987' + moderatorURL: 'http://localhost:6080/room/room-456?secret=789012' + publisherURL: 'http://localhost:6080/room/room-456?secret=210987' pagination: isTruncated: false maxItems: 10 @@ -90,10 +90,10 @@ content: summary: Response containing only moderator and publisher URLs value: rooms: - - 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' + - 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-rooms-marked-for-deletion.yaml b/backend/openapi/components/responses/success-rooms-marked-for-deletion.yaml index 264a401c..36509b11 100644 --- a/backend/openapi/components/responses/success-rooms-marked-for-deletion.yaml +++ b/backend/openapi/components/responses/success-rooms-marked-for-deletion.yaml @@ -1,5 +1,5 @@ description: > - All specified rooms were marked error for deletion (due to active participants) + All specified rooms were marked for deletion (due to active participants) and will be removed once all participants leave. content: application/json: diff --git a/backend/openapi/components/responses/validation-error.yaml b/backend/openapi/components/responses/validation-error.yaml index 2ffee30b..5670c6ec 100644 --- a/backend/openapi/components/responses/validation-error.yaml +++ b/backend/openapi/components/responses/validation-error.yaml @@ -1,4 +1,4 @@ -description: Unprocessable Entity — Invalid request body +description: Unprocessable Entity — Invalid request content: application/json: schema: diff --git a/backend/openapi/components/responses/webhook-success.yaml b/backend/openapi/components/responses/webhook-success.yaml index 9eb0dc33..26a84f01 100644 --- a/backend/openapi/components/responses/webhook-success.yaml +++ b/backend/openapi/components/responses/webhook-success.yaml @@ -1,7 +1,7 @@ -description: > - Webhook received and processed successfully. +description: | + Webhook received and processed successfully. - Important: Webhook endpoints must return HTTP 200 OK promptly to acknowledge receipt. - Any processing should be done asynchronously after responding. - - Non-200 responses or timeouts will trigger retries according to the webhook delivery policy. \ No newline at end of file + > **Important:** Webhook endpoints must return HTTP 200 OK promptly to acknowledge receipt. + > Any processing should be done asynchronously after responding. + > + > Non-200 responses or timeouts will trigger retries according to the webhook delivery policy. diff --git a/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml b/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml index e304b96b..fcc0a4ae 100644 --- a/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml +++ b/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml @@ -23,8 +23,7 @@ properties: room: type: string description: > - The ID of the room associated with the participant. - example: roomId + Unique identifier of the room to which the participant is assigned. canPublish: type: boolean description: > @@ -61,5 +60,5 @@ properties: canChangeVirtualBackground: type: boolean description: > - Indicates whether the participant can change virtual background in the room. + Indicates whether the participant can change their own virtual background. example: true diff --git a/backend/openapi/components/schemas/internal/security-preferences.yaml b/backend/openapi/components/schemas/internal/security-preferences.yaml index 08891917..777cc45d 100644 --- a/backend/openapi/components/schemas/internal/security-preferences.yaml +++ b/backend/openapi/components/schemas/internal/security-preferences.yaml @@ -16,7 +16,9 @@ AuthenticationPreferences: - single-user default: single-user example: single-user - description: The authentication method to use. + description: | + Specifies the authentication method used to access the application. + - `single-user`: Only one user account exists, which has administrative privileges and is used for all access. authModeToAccessRoom: type: string enum: @@ -25,4 +27,8 @@ AuthenticationPreferences: - all_users default: none example: none - description: The authentication mode to access a room. + description: | + Specifies who is required to authenticate before accessing a room: + - `none`: No authentication required. + - `moderators_only`: Only moderators need to authenticate. + - `all_users`: All users must authenticate. diff --git a/backend/openapi/components/schemas/internal/user.yaml b/backend/openapi/components/schemas/internal/user.yaml index 706d401c..3bdae212 100644 --- a/backend/openapi/components/schemas/internal/user.yaml +++ b/backend/openapi/components/schemas/internal/user.yaml @@ -8,5 +8,6 @@ properties: type: array items: type: string + enum: ['admin', 'user'] example: ['admin', 'user'] description: A list of roles assigned to the authenticated user. diff --git a/backend/openapi/components/schemas/internal/webhooks-preferences.yaml b/backend/openapi/components/schemas/internal/webhooks-preferences.yaml index b2686ee5..42c71ac1 100644 --- a/backend/openapi/components/schemas/internal/webhooks-preferences.yaml +++ b/backend/openapi/components/schemas/internal/webhooks-preferences.yaml @@ -6,5 +6,6 @@ properties: description: Indicates whether webhooks are enabled or disabled. url: type: string + format: uri example: 'https://example.com/webhook' description: The URL to which webhooks will be sent. This is only mandatory if webhooks are enabled. diff --git a/backend/openapi/components/schemas/meet-pagination.yaml b/backend/openapi/components/schemas/meet-pagination.yaml index b9920092..adec2c04 100644 --- a/backend/openapi/components/schemas/meet-pagination.yaml +++ b/backend/openapi/components/schemas/meet-pagination.yaml @@ -3,13 +3,13 @@ properties: isTruncated: type: boolean description: > - Indicates if there are more elements to retrieve. - If true, use the `nextPageToken` to fetch the next set of elements. + Indicates if there are more items to retrieve. + If true, use the `nextPageToken` to fetch the next set of items. nextPageToken: type: [string, 'null'] - description: The token to retrieve the next page of elements. + description: The token to retrieve the next page of items. maxItems: type: integer description: > - Maximum number of elements returned in a single response page. + Maximum number of items returned in a single response page. Corresponds to the `maxItems` query parameter in the request. diff --git a/backend/openapi/components/schemas/meet-room-options.yaml b/backend/openapi/components/schemas/meet-room-options.yaml index 60d88ab2..adc0a82c 100644 --- a/backend/openapi/components/schemas/meet-room-options.yaml +++ b/backend/openapi/components/schemas/meet-room-options.yaml @@ -3,15 +3,14 @@ properties: autoDeletionDate: type: [number, 'null'] example: 1900000000000 - description: > - The date and time when the room will be deleted (must be one hour in the future or more) represented in milliseconds since the Unix epoch. + description: | + The timestamp (in milliseconds since the Unix epoch) specifying when the room will be automatically deleted. + This must be at least one hour in the future. - After this date, the room will be automatically deleted and no new participants can join. + After this time, the room is closed to new participants and scheduled for deletion. + It will 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. + If not set, the room remains active until manually deleted. roomIdPrefix: type: string example: 'room' diff --git a/backend/openapi/components/schemas/meet-room.yaml b/backend/openapi/components/schemas/meet-room.yaml index 9beadb6f..5f169d77 100644 --- a/backend/openapi/components/schemas/meet-room.yaml +++ b/backend/openapi/components/schemas/meet-room.yaml @@ -18,15 +18,14 @@ properties: autoDeletionDate: type: [number, 'null'] example: 1900000000000 - description: > - The date and time when the room will be deleted (must be one hour in the future or more) represented in milliseconds since the Unix epoch. + description: | + The timestamp (in milliseconds since the Unix epoch) specifying when the room will be automatically deleted. + This must be at least one hour in the future. - After this date, the room will be automatically deleted and no new participants can join. + After this time, the room is closed to new participants and scheduled for deletion. + It will 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. + If not set, the room remains active until manually deleted. preferences: $ref: meet-room-preferences.yaml#/MeetRoomPreferences description: The preferences for the room. @@ -38,13 +37,13 @@ properties: # this limit, new participants will not be allowed to join. moderatorURL: type: string - example: 'http://localhost:6080/room/room-123/?secret=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 + The URL for the moderator participants to join the room. The moderator role has special permissions to manage the room and participants. publisherURL: type: string - example: 'http://localhost:6080/room/room-123/?secret=654321' + 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 + The URL for the publisher participants to join the room. The publisher role has permissions to publish audio and video streams to the room. diff --git a/backend/openapi/components/schemas/webhook-base-event.yaml b/backend/openapi/components/schemas/webhook-base-event.yaml index 181dd6c5..98a38fc4 100644 --- a/backend/openapi/components/schemas/webhook-base-event.yaml +++ b/backend/openapi/components/schemas/webhook-base-event.yaml @@ -1,17 +1,17 @@ type: object required: - - creationDate - - event - - data + - creationDate + - event + - data properties: - creationDate: - type: number - description: The date when the event was created (milliseconds since the Unix epoch). - example: 1620000000000 - event: - type: string - description: Event type identifier. - example: webhookEvent - data: - type: object - description: The data associated with the event. \ No newline at end of file + creationDate: + type: number + description: The date when the event was created (milliseconds since the Unix epoch). + example: 1620000000000 + event: + type: string + description: Event type identifier. + example: webhookEvent + data: + type: object + description: The data associated with the event. diff --git a/backend/openapi/components/security.yaml b/backend/openapi/components/security.yaml index 1a367f27..ef169cc0 100644 --- a/backend/openapi/components/security.yaml +++ b/backend/openapi/components/security.yaml @@ -15,7 +15,7 @@ refreshTokenCookie: 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. + The JWT token to refresh the access token when it expires.. participantTokenCookie: type: apiKey name: OvMeetParticipantToken diff --git a/backend/openapi/openvidu-meet-api.yaml b/backend/openapi/openvidu-meet-api.yaml index 72d2a3ab..29bd27f9 100644 --- a/backend/openapi/openvidu-meet-api.yaml +++ b/backend/openapi/openvidu-meet-api.yaml @@ -26,8 +26,6 @@ paths: components: securitySchemes: $ref: './components/security.yaml' - # responses: - # $ref: './components/responses.yaml' schemas: MeetRoom: $ref: components/schemas/meet-room.yaml diff --git a/backend/openapi/paths/internal/auth.yaml b/backend/openapi/paths/internal/auth.yaml index f7b31b50..267d71b2 100644 --- a/backend/openapi/paths/internal/auth.yaml +++ b/backend/openapi/paths/internal/auth.yaml @@ -27,28 +27,11 @@ - Internal API - Authentication responses: '200': - 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' + $ref: '../../components/responses/internal/success-user-logout.yaml' /auth/refresh: post: operationId: refreshAccessToken - summary: Refresh the access token + summary: Refresh access token description: > Refreshes the access token using the refresh token. The new access token is returned in a cookie. @@ -68,10 +51,11 @@ post: operationId: createApiKey summary: Create a new API key - description: > - Creates a new API key. Only one API key can be created in the system. - If an API key already exists, it will be replaced with the new one. - The API key is returned in the response. + description: | + Creates a new API key, returning it in the response. + + > **Note:** Only one API key can be created in the system. + > If an API key already exists, it will be replaced with the new one. tags: - Internal API - Authentication security: @@ -84,8 +68,11 @@ get: operationId: getApiKeys summary: Get API keys - description: > + description: | Retrieves the existing API keys. + + > **Note:** Only one API key can exist in the system. + > If no API key exists, an empty array will be returned. tags: - Internal API - Authentication security: @@ -106,9 +93,6 @@ - accessTokenCookie: [] responses: '204': - description: Successfully deleted the API key + description: Successfully deleted the API key. No content is returned. '500': $ref: '../../components/responses/internal-server-error.yaml' - - - diff --git a/backend/openapi/paths/internal/global-preferences.yaml b/backend/openapi/paths/internal/global-preferences.yaml index c182b95b..add6233a 100644 --- a/backend/openapi/paths/internal/global-preferences.yaml +++ b/backend/openapi/paths/internal/global-preferences.yaml @@ -45,7 +45,7 @@ operationId: testWebhookUrl summary: Test webhook URL description: > - Tests the provided webhook URL to ensure it is reachable and valid. + Tests the provided webhook URL to ensure it is valid and reachable. tags: - Internal API - Global Preferences requestBody: diff --git a/backend/openapi/paths/internal/meetings.yaml b/backend/openapi/paths/internal/meetings.yaml index c087c9ae..3614c8fb 100644 --- a/backend/openapi/paths/internal/meetings.yaml +++ b/backend/openapi/paths/internal/meetings.yaml @@ -2,8 +2,8 @@ delete: operationId: endMeeting summary: End a meeting - description: > - Ends a meeting in an OpenVidu Meet room. This will stop all recordings and disconnect all participants. + description: | + Ends the current meeting in an OpenVidu Meet room. This will stop all recordings and disconnect all participants. This endpoint is idempotent. If the meeting is already ended, it will return a success response without any action. tags: @@ -29,9 +29,9 @@ /meetings/{roomId}/participants/{participantName}: delete: operationId: disconnectParticipant - summary: Delete a participant from a meeting + summary: Kick a participant from a meeting description: > - Deletes a participant from an OpenVidu Meet room. This will disconnect the participant from the meeting. + Kicks a participant from the current meeting in an OpenVidu Meet room. tags: - Internal API - Meetings security: diff --git a/backend/openapi/paths/internal/participants.yaml b/backend/openapi/paths/internal/participants.yaml index 59d37838..a1c42b4c 100644 --- a/backend/openapi/paths/internal/participants.yaml +++ b/backend/openapi/paths/internal/participants.yaml @@ -1,7 +1,7 @@ /participants/token: post: operationId: generateParticipantToken - summary: Generate a token for a participant + summary: Generate token for participant description: > Generates a token for a participant to join an OpenVidu Meet room. tags: @@ -30,7 +30,7 @@ /participants/token/refresh: post: operationId: refreshParticipantToken - summary: Refresh a token for a participant + summary: Refresh token for participant description: > Refresh a token for a participant in an OpenVidu Meet room. tags: diff --git a/backend/openapi/paths/internal/recordings.yaml b/backend/openapi/paths/internal/recordings.yaml index ec92ab0b..3a20e666 100644 --- a/backend/openapi/paths/internal/recordings.yaml +++ b/backend/openapi/paths/internal/recordings.yaml @@ -35,9 +35,10 @@ post: operationId: stopRecording summary: Stop a recording - description: > + description: | Stops a recording with the specified recording ID. - The recording must be in an `ACTIVE` state; otherwise, a 409 error is returned. + + > **Note:** The recording must be in an `ACTIVE` state; otherwise, a 409 error is returned. tags: - Internal API - Recordings security: diff --git a/backend/openapi/paths/internal/rooms.yaml b/backend/openapi/paths/internal/rooms.yaml index 45acc758..0a614d5d 100644 --- a/backend/openapi/paths/internal/rooms.yaml +++ b/backend/openapi/paths/internal/rooms.yaml @@ -106,9 +106,10 @@ get: operationId: getRoomRoleAndPermissions summary: Get room role and permissions - description: > + description: | Retrieves the role and associated permissions that a participant will have in a specified OpenVidu Meet room when using the URL thant contains the given secret value. + This endpoint is useful for checking the participant's role and permissions before joining the room. tags: - Internal API - Rooms diff --git a/backend/openapi/paths/recordings.yaml b/backend/openapi/paths/recordings.yaml index 1d56d682..19baef46 100644 --- a/backend/openapi/paths/recordings.yaml +++ b/backend/openapi/paths/recordings.yaml @@ -2,12 +2,12 @@ get: operationId: getRecordings summary: Get all recordings - description: > + description: | Retrieves a paginated list of all recordings available in the system. You can apply filters to narrow down the results based on specific criteria. > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method, - the `roomId` filter will be ignored and only recordings associated with the room included in the token will be returned. + > the `roomId` filter will be ignored and only recordings associated with the room included in the token will be returned. tags: - OpenVidu Meet - Recordings security: @@ -15,27 +15,7 @@ - accessTokenCookie: [] - recordingTokenCookie: [] parameters: - # - name: status - # in: query - # required: false - # description: | - # Filter recordings by their status. - - # Possible values: - # - `STARTING` - # - `ACTIVE` - # - `ENDING` - # - `COMPLETE` - # - `FAILED` - # - `ABORTED` - # - `LIMITED_REACHED` - - # You can provide multiple statuses as a comma-separated list (e.g., `status=ACTIVE,FAILED`). - # If not specified, recordings with any status will be returned. - - # > ⚠️ **Note:** Using this filter may impact performance for large datasets. - # schema: - # type: string + # - $ref: '../components/parameters/recording-status.yaml' - $ref: '../components/parameters/recording-fields.yaml' - $ref: '../components/parameters/room-id-query.yaml' - $ref: '../components/parameters/max-items.yaml' @@ -55,12 +35,12 @@ delete: operationId: bulkDeleteRecordings summary: Bulk delete recordings - description: > + description: | Deletes multiple recordings at once with the specified recording IDs. > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method, - all specified recordings must belong to the same room included in the token. - If a recording does not belong to that room, it will not be deleted. + > all specified recordings must belong to the same room included in the token. + > If a recording does not belong to that room, it will not be deleted. tags: - OpenVidu Meet - Recordings security: @@ -89,13 +69,13 @@ get: operationId: downloadRecordings summary: Download recordings - description: > + description: | Downloads multiple recordings as a ZIP file with the specified recording IDs. The ZIP file will contain all recordings in MP4 format. > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method, - all specified recordings must belong to the same room included in the token. - If a recording does not belong to that room, it will not be included in the ZIP file. + > all specified recordings must belong to the same room included in the token. + > If a recording does not belong to that room, it will not be included in the ZIP file. tags: - OpenVidu Meet - Recordings security: @@ -145,6 +125,7 @@ - recordingTokenCookie: [] parameters: - $ref: '../components/parameters/recording-id.yaml' + - $ref: '../components/parameters/recording-secret.yaml' responses: '200': $ref: '../components/responses/success-get-recording.yaml' @@ -163,9 +144,11 @@ delete: operationId: deleteRecording summary: Delete a recording - description: > - Deletes a recording with the specified recording. - The recording will only be deleted if it exists and is not in progress (i.e., not in a state such as `ACTIVE`, `STARTING`, or `ENDING`). + description: | + Deletes a recording with the specified recording ID. + + > ⚠️ **Note:** The recording will only be deleted if it exists and is not in progress + > (i.e., not in a state such as `ACTIVE`, `STARTING`, or `ENDING`). tags: - OpenVidu Meet - Recordings security: @@ -193,9 +176,10 @@ get: operationId: getRecordingMedia summary: Get recording media - description: > + description: | Retrieves the media of a recording with the specified recording ID. The media is returned in a binary format suitable for video playback. + This endpoint supports range requests, allowing partial content retrieval for video playback without downloading the entire file. tags: @@ -210,7 +194,7 @@ - $ref: '../components/parameters/recording-range.yaml' responses: '200': - description: Successfully streaming the full recording + description: Successfully retrieved the full recording media headers: Accept-Ranges: $ref: '../components/headers/accept-ranges.yaml' @@ -224,7 +208,7 @@ type: string format: binary '206': - description: Partial content streaming based on byte range + description: Successfully retrieved a partial range of the recording media headers: Accept-Ranges: $ref: '../components/headers/accept-ranges.yaml' @@ -256,8 +240,8 @@ schema: $ref: '../components/schemas/error.yaml' example: - code: 416 - message: 'Requested range not satisfiable' + error: Recording Error + message: 'Recording "room-123--EG_XYZ--XX445" range not satisfiable. File size: 123456789' '422': $ref: '../components/responses/validation-error.yaml' '500': @@ -266,9 +250,10 @@ get: operationId: getRecordingUrl summary: Get recording URL - description: > + description: | Retrieves the URL of a recording with the specified recording ID. This URL is intended to be shared with people who do not have direct access to the recording. + It can be configured to be accessible by anyone (public access) or restricted to authenticated users only, depending on the `privateAccess` query parameter. tags: diff --git a/backend/openapi/paths/rooms.yaml b/backend/openapi/paths/rooms.yaml index 9c8a3043..cc6faea9 100644 --- a/backend/openapi/paths/rooms.yaml +++ b/backend/openapi/paths/rooms.yaml @@ -3,7 +3,7 @@ operationId: createRoom summary: Create a room description: > - Creates a new OpenVidu Meet room with the specified expiration date. + Creates a new OpenVidu Meet room. The room will be available for participants to join using the generated URLs. tags: - OpenVidu Meet - Room @@ -29,6 +29,7 @@ summary: Get all rooms description: > Retrieves a paginated list of all rooms available in the system. + You can apply filters to narrow down the results based on specific criteria. tags: - OpenVidu Meet - Room security: @@ -53,7 +54,7 @@ delete: operationId: bulkDeleteRooms summary: Bulk delete rooms - description: > + 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 @@ -120,7 +121,7 @@ delete: operationId: deleteRoom summary: Delete a room - description: > + description: | Deletes an OpenVidu Meet room with the specified room ID. If the room has active participants, it will be marked for deletion diff --git a/backend/openapi/webhooks/webhooks.yaml b/backend/openapi/webhooks/webhooks.yaml index 9c2e3d58..96323a32 100644 --- a/backend/openapi/webhooks/webhooks.yaml +++ b/backend/openapi/webhooks/webhooks.yaml @@ -1,7 +1,7 @@ recordingStarted: post: summary: Recording started - description: > + description: | This webhook is triggered when a recording starts. > The recording can be in the `STARTING` status for a few seconds before it becomes `ACTIVE`. @@ -31,7 +31,7 @@ recordingStarted: - properties: status: type: string - enum: [STARTING] + enum: [STARTING, ACTIVE] description: The status of the recording. example: STARTING responses: @@ -41,7 +41,7 @@ recordingStarted: recordingUpdated: post: summary: Recording updated - description: > + description: | This webhook is triggered when a recording update occurs. > This update can be due to a change in the recording status (e.g., from `STARTING` to `ACTIVE`). @@ -81,10 +81,11 @@ recordingUpdated: recordingEnded: post: summary: Recording ended - description: > + description: | This webhook is triggered when a recording ends. - > The recording can end due to various reasons, such as the user stopping the recording or the recording reaching its maximum duration. + > The recording can end due to various reasons, such as the user stopping the recording + > or the recording reaching its maximum duration. operationId: recordingEndedWebhook parameters: - $ref: ../components/parameters/x-timestamp.yaml @@ -112,7 +113,7 @@ recordingEnded: - properties: status: type: string - enum: [COMPLETE, FAILED, ABORTED, LIMITED_REACHED] + enum: [COMPLETE, FAILED, ABORTED, LIMIT_REACHED] description: The status of the recording. example: COMPLETE endDate: