openapi: update specification to reflect code changes in API endpoints

This commit is contained in:
juancarmore 2025-09-04 00:23:04 +02:00
parent 8ac17ad5aa
commit 32055b98c4
29 changed files with 508 additions and 116 deletions

View File

@ -1,8 +0,0 @@
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: boolean

View File

@ -0,0 +1,16 @@
name: withMeeting
in: query
description: |
Policy for room deletion when it has an active meeting. Options are:
- force: The meeting will be ended, and the room will be deleted without waiting for participants to leave.
- when_meeting_ends: The room will be deleted when the meeting ends.
- fail: The deletion will fail if there is an active meeting.
required: false
schema:
type: string
enum:
- force
- when_meeting_ends
- fail
default: fail
example: fail

View File

@ -0,0 +1,16 @@
name: withRecordings
in: query
description: |
Policy for room deletion when it has recordings. Options are:
- force: The room and its recordings will be deleted.
- close: The room will be closed instead of deleted, maintaining its recordings.
- fail: The deletion will fail if the room has recordings.
required: false
schema:
type: string
enum:
- force
- close
- fail
default: fail
example: fail

View File

@ -0,0 +1,53 @@
description: >
**Mixed results**. Some recordings were deleted successfully while others
could not be deleted (e.g., due to being in progress or not found).
content:
application/json:
schema:
type: object
properties:
message:
type: string
deleted:
type: array
items:
type: string
description: List of recordings that were deleted successfully.
failed:
type: array
description: List of recordings that could not be deleted along with the corresponding error messages.
items:
type: object
properties:
recordingId:
type: string
description: The unique identifier of the recording that was not deleted.
example: 'room-123--EG_XYZ--XX447'
error:
type: string
description: A message explaining why the deletion failed.
example: 'Recording not found'
examples:
partial_deletion_with_errors:
summary: Some recordings were deleted successfully, others failed
value:
message: '2 recording(s) could not be deleted'
deleted:
- 'room-123--EG_XYZ--XX445'
- 'room-123--EG_ZYX--XX446'
failed:
- recordingId: 'room-123--EG_XYZ--XX447'
error: 'Recording not found'
- recordingId: 'room-123--EG_XYZ--XX448'
error: 'Recording in progress'
no_deletion_performed:
summary: No recordings were deleted
value:
message: '2 recording(s) could not be deleted'
deleted: []
failed:
- recordingId: 'room-123--EG_XYZ--XX447'
error: 'Recording not found'
- recordingId: 'room-123--EG_ZYX--XX448'
error: 'Recording in progress'

View File

@ -0,0 +1,76 @@
description: >
**Mixed results**. Some rooms were successfully processed for deletion while others were not.
content:
application/json:
schema:
type: object
properties:
message:
type: string
successful:
type: array
items:
type: object
properties:
successCode:
type: string
enum:
- room_deleted
- room_with_active_meeting_deleted
- room_with_active_meeting_scheduled_to_be_deleted
- room_and_recordings_deleted
- room_closed
- room_with_active_meeting_and_recordings_deleted
- room_with_active_meeting_closed
- room_with_active_meeting_and_recordings_scheduled_to_be_deleted
- room_with_active_meeting_scheduled_to_be_closed
description: A code representing the success scenario
message:
type: string
description: A message providing additional context about the success
description: List of rooms that were successfully processed for deletion
failed:
type: array
items:
type: object
properties:
roomId:
type: string
error:
type: string
description: Name of the error
message:
type: string
description: Description of the error
description: List of rooms that failed to process while deleting
examples:
partial_deletion_with_errors:
summary: Some rooms were successfully processed for deletion, others failed
value:
message: '2 room(s) failed to process while deleting'
successful:
- roomId: room-123
successCode: room_deleted
message: Room 'room-123' deleted successfully
- roomId: room-456
successCode: room_with_active_meeting_deleted
message: Room 'room-456' with active meeting deleted successfully
failed:
- roomId: room-789
error: Room Error
message: Room 'room-789' not found
- roomId: room-101
error: room_has_active_meeting
message: Room 'room-101' cannot be deleted because it has an active meeting
no_deletion_performed:
summary: No rooms were successfully processed for deletion
value:
message: '2 room(s) failed to process for deletion'
successful: []
failed:
- roomId: room-123
error: Room Error
message: Room 'room-123' not found
- roomId: room-456
error: room_has_active_meeting
message: Room 'room-456' cannot be deleted because it has an active meeting

View File

@ -0,0 +1,26 @@
description: Room failed to process deletion
content:
application/json:
schema:
$ref: '../schemas/error.yaml'
examples:
room_has_active_meeting:
value:
error: room_has_active_meeting
message: Room 'room-123' cannot be deleted because it has an active meeting
room_has_recordings:
value:
error: room_has_recordings
message: Room 'room-123' cannot be deleted because it has recordings
room_with_active_meeting_has_recordings:
value:
error: room_with_active_meeting_has_recordings
message: Room 'room-123' with active meeting cannot be deleted because it has recordings
room_with_active_meeting_has_recordings_cannot_schedule_deletion:
value:
error: room_with_active_meeting_has_recordings_cannot_schedule_deletion
message: Room 'room-123' with active meeting cannot be scheduled to be deleted because it has recordings
room_with_recordings_has_active_meeting:
value:
error: room_with_recordings_has_active_meeting
message: Room 'room-123' with recordings cannot be deleted because it has an active meeting

View File

@ -0,0 +1,8 @@
description: Room closed
content:
application/json:
schema:
$ref: '../../schemas/error.yaml'
example:
error: 'Room Error'
message: Room 'room_123' is closed and cannot be joined

View File

@ -6,4 +6,4 @@ content:
properties:
message:
type: string
example: 'Password changed successfully'
example: Password for user 'admin' changed successfully

View File

@ -1,4 +1,4 @@
description: Successfully disconnected the participant
description: Successfully deleted API keys
content:
application/json:
schema:
@ -6,4 +6,4 @@ content:
properties:
message:
type: string
example: 'Participant deleted'
example: 'API keys deleted successfully'

View File

@ -6,4 +6,4 @@ content:
properties:
message:
type: string
example: 'Meeting ended successfully'
example: Meeting in room 'room-123' ended successfully

View File

@ -0,0 +1,9 @@
description: Successfully kicked the participant
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Participant 'Alice' kicked successfully from room 'room-123'

View File

@ -9,4 +9,4 @@ content:
properties:
message:
type: string
example: 'Token refreshed'
example: Access token for user 'admin' successfully refreshed

View File

@ -11,4 +11,4 @@ content:
properties:
message:
type: string
example: 'Login succeeded'
example: User 'admin' logged in successfully

View File

@ -1,49 +1,18 @@
description: >
**Mixed results**. Some recordings were deleted successfully while others
could not be deleted (e.g., due to being in progress or not found).
description: All specified recordings were deleted successfully.
content:
application/json:
schema:
type: object
properties:
message:
type: string
deleted:
type: array
items:
type: string
description: List of recordings that were deleted successfully.
notDeleted:
type: array
description: List of recordings that could not be deleted along with the corresponding error messages.
items:
type: object
properties:
recordingId:
type: string
description: The unique identifier of the recording that was not deleted.
example: 'room-123--EG_XYZ--XX447'
error:
type: string
description: A message explaining why the deletion failed.
example: 'Recording not found'
examples:
partial_deletion_with_errors:
summary: Some recordings were deleted successfully, others failed
value:
deleted:
- 'room-123--EG_XYZ--XX445'
- 'room-123--EG_ZYX--XX446'
notDeleted:
- recordingId: 'room-123--EG_XYZ--XX447'
error: 'Recording not found'
- recordingId: 'room-123--EG_XYZ--XX448'
error: 'Recording in progress'
no_deletion_performed:
summary: No recordings were deleted
value:
deleted: []
notDeleted:
- recordingId: 'room-123--EG_XYZ--XX447'
error: 'Recording not found'
- recordingId: 'room-123--EG_ZYX--XX448'
error: 'Recording in progress'
example:
message: "All recordings deleted successfully"
deleted:
- 'room-123--EG_XYZ--XX445'
- 'room-123--EG_ZYX--XX446'

View File

@ -1,27 +1,39 @@
description: >
**Mixed results**. Some rooms were deleted immediately while others were
marked for deletion (due to active participants).
description: All specified rooms were successfully processed for deletion.
content:
application/json:
schema:
type: object
properties:
deleted:
message:
type: string
successful:
type: array
items:
type: string
description: List of rooms that were deleted immediately
markedForDeletion:
type: array
items:
type: string
description: >-
List of rooms that were marked for deletion but not actually deleted.
These rooms will be deleted when all participants leave.
type: object
properties:
successCode:
type: string
enum:
- room_deleted
- room_with_active_meeting_deleted
- room_with_active_meeting_scheduled_to_be_deleted
- room_and_recordings_deleted
- room_closed
- room_with_active_meeting_and_recordings_deleted
- room_with_active_meeting_closed
- room_with_active_meeting_and_recordings_scheduled_to_be_deleted
- room_with_active_meeting_scheduled_to_be_closed
description: A code representing the success scenario
message:
type: string
description: A message providing additional context about the success
description: List of rooms that were successfully processed for deletion
example:
deleted:
- 'room-123'
- 'room-456'
markedForDeletion:
- 'room-789'
- 'room-101'
message: 'All rooms successfully processed for deletion'
successful:
- roomId: room-123
successCode: room_deleted
message: Room 'room-123' deleted successfully
- roomId: room-456
successCode: room_with_active_meeting_deleted
message: Room 'room-456' with active meeting deleted successfully

View File

@ -0,0 +1,10 @@
description: Successful deletion of the recording
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: Recording 'room-123--EG_XYZ--XX445' deleted successfully

View File

@ -11,6 +11,9 @@ content:
roomName: 'room'
creationDate: 1620000000000
autoDeletionDate: 1900000000000
autoDeletionPolicy:
withMeeting: when_meeting_ends
withRecordings: close
preferences:
chatPreferences:
enabled: true
@ -20,6 +23,8 @@ content:
enabled: true
moderatorUrl: 'http://localhost:6080/room/room-123?secret=123456'
speakerUrl: 'http://localhost:6080/room/room-123?secret=654321'
status: open
meetingEndAction: none
fields=roomId:
summary: Response with only the roomId

View File

@ -20,6 +20,9 @@ content:
roomName: 'room'
creationDate: 1620000000000
autoDeletionDate: 1900000000000
autoDeletionPolicy:
withMeeting: when_meeting_ends
withRecordings: close
preferences:
chatPreferences:
enabled: true
@ -29,10 +32,15 @@ content:
enabled: true
moderatorUrl: 'http://localhost:6080/room/room-123?secret=123456'
speakerUrl: 'http://localhost:6080/room/room-123?secret=654321'
status: open
meetingEndAction: none
- roomId: 'room-456'
roomName: 'room'
creationDate: 1620001000000
autoDeletionDate: 1900000000000
autoDeletionPolicy:
withMeeting: when_meeting_ends
withRecordings: close
preferences:
chatPreferences:
enabled: false
@ -42,6 +50,8 @@ content:
enabled: false
moderatorUrl: 'http://localhost:6080/room/room-456?secret=789012'
speakerUrl: 'http://localhost:6080/room/room-456?secret=210987'
status: open
meetingEndAction: none
pagination:
isTruncated: false
maxItems: 10

View File

@ -1,12 +0,0 @@
description: >
The room was marked for deletion (due to active participants)
and will be removed once all participants leave.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: Room 'room-123' marked for deletion

View File

@ -0,0 +1,44 @@
description: Room was successfully processed for deletion
content:
application/json:
schema:
type: object
properties:
successCode:
type: string
enum:
- room_deleted
- room_with_active_meeting_deleted
- room_and_recordings_deleted
- room_closed
- room_with_active_meeting_and_recordings_deleted
- room_with_active_meeting_closed
description: A code representing the success scenario
message:
type: string
description: A message providing additional context about the success
examples:
room_deleted:
value:
successCode: room_deleted
message: Room 'room-123' deleted successfully
room_with_active_meeting_deleted:
value:
successCode: room_with_active_meeting_deleted
message: Room 'room-123' with active meeting deleted successfully
room_and_recordings_deleted:
value:
successCode: room_and_recordings_deleted
message: Room 'room-123' and its recordings deleted successfully
room_closed:
value:
successCode: room_closed
message: Room 'room-123' has been closed instead of deleted because it has recordings
room_with_active_meeting_and_recordings_deleted:
value:
successCode: room_with_active_meeting_and_recordings_deleted
message: Room 'room-123' with active meeting and its recordings deleted successfully
room_with_active_meeting_closed:
value:
successCode: room_with_active_meeting_closed
message: Room 'room-123' with active meeting has been closed instead of deleted because it has recordings

View File

@ -0,0 +1,76 @@
description: Room was successfully scheduled to be deleted or closed
content:
application/json:
schema:
type: object
properties:
successCode:
type: string
enum:
- room_with_active_meeting_scheduled_to_be_deleted
- room_with_active_meeting_and_recordings_scheduled_to_be_deleted
- room_with_active_meeting_scheduled_to_be_closed
description: A code representing the success scenario
message:
type: string
description: A message providing additional context about the success
room:
$ref: '../schemas/meet-room.yaml'
examples:
room_with_active_meeting_scheduled_to_be_deleted:
value:
successCode: room_with_active_meeting_scheduled_to_be_deleted
message: Room 'room-123' with active meeting scheduled to be deleted when the meeting ends
room:
roomId: room-123
roomName: room
creationDate: 1620000000000
preferences:
chatPreferences:
enabled: true
recordingPreferences:
enabled: false
virtualBackgroundPreferences:
enabled: true
moderatorUrl: 'http://localhost:6080/room/room-123?secret=123456'
speakerUrl: 'http://localhost:6080/room/room-123?secret=654321'
status: active_meeting
meetingEndAction: delete
room_with_active_meeting_and_recordings_scheduled_to_be_deleted:
value:
successCode: room_with_active_meeting_and_recordings_scheduled_to_be_deleted
message: Room 'room-123' with active meeting and its recordings scheduled to be deleted when the meeting ends
room:
roomId: room-123
roomName: room
creationDate: 1620000000000
preferences:
chatPreferences:
enabled: true
recordingPreferences:
enabled: false
virtualBackgroundPreferences:
enabled: true
moderatorUrl: 'http://localhost:6080/room/room-123?secret=123456'
speakerUrl: 'http://localhost:6080/room/room-123?secret=654321'
status: active_meeting
meetingEndAction: delete
room_with_active_meeting_scheduled_to_be_closed:
value:
successCode: room_with_active_meeting_scheduled_to_be_closed
message: Room 'room-123' with active meeting scheduled to be closed when the meeting ends because it has recordings
room:
roomId: room-123
roomName: room
creationDate: 1620000000000
preferences:
chatPreferences:
enabled: true
recordingPreferences:
enabled: false
virtualBackgroundPreferences:
enabled: true
moderatorUrl: 'http://localhost:6080/room/room-123?secret=123456'
speakerUrl: 'http://localhost:6080/room/room-123?secret=654321'
status: active_meeting
meetingEndAction: close

View File

@ -20,6 +20,34 @@ properties:
It will be removed after the last participant leaves (graceful deletion).
If not set, the room remains active until manually deleted.
autoDeletionPolicy:
type: object
description: >
Policy for automatic deletion of the room and its contents. This includes
settings for how the room should be handled when certain conditions are met.
properties:
withMeeting:
type: string
enum:
- force
- when_meeting_ends
default: when_meeting_ends
example: when_meeting_ends
description: |
Policy for automatic deletion when the room has an active meeting. Options are:
- force: The meeting will be ended, and the room will be deleted without waiting for participants to leave.
- when_meeting_ends: The room will be deleted when the meeting ends.
withRecordings:
type: string
enum:
- force
- close
default: close
example: close
description: |
Policy for automatic deletion when the room has recordings. Options are:
- force: The room and its recordings will be deleted.
- close: The room will be closed instead of deleted, maintaining its recordings.
# maxParticipants:
# type: integer
# example: 10

View File

@ -30,6 +30,34 @@ properties:
It will be removed after the last participant leaves (graceful deletion).
If not set, the room remains active until manually deleted.
autoDeletionPolicy:
type: object
description: >
Policy for automatic deletion of the room and its contents. This includes
settings for how the room should be handled when certain conditions are met.
properties:
withMeeting:
type: string
enum:
- force
- when_meeting_ends
default: when_meeting_ends
example: when_meeting_ends
description: |
Policy for automatic deletion when the room has an active meeting. Options are:
- force: The meeting will be ended, and the room will be deleted without waiting for participants to leave.
- when_meeting_ends: The room will be deleted when the meeting ends.
withRecordings:
type: string
enum:
- force
- close
default: close
example: close
description: |
Policy for automatic deletion when the room has recordings. Options are:
- force: The room and its recordings will be deleted.
- close: The room will be closed instead of deleted, maintaining its recordings.
preferences:
$ref: meet-room-preferences.yaml#/MeetRoomPreferences
description: The preferences for the room.
@ -51,3 +79,27 @@ properties:
description: >
The URL for the speaker participants to join the room. The speaker role has permissions to publish audio and
video streams to the room.
status:
type: string
enum:
- open
- active_meeting
- closed
example: open
description: |
The current status of the room. Options are:
- open: The room is open and available to host a meeting.
- active_meeting: There is an active meeting in progress in the room.
- closed: The room is closed to hosting new meetings.
meetingEndAction:
type: string
enum:
- none
- delete
- close
example: none
description: |
The action to take when the meeting ends. Options are:
- none: No action will be taken.
- close: The room will be closed.
- delete: The room (and its recordings if any) will be deleted.

View File

@ -92,7 +92,7 @@
security:
- accessTokenCookie: []
responses:
'204':
description: Successfully deleted the API key. No content is returned.
'200':
$ref: '../../components/responses/internal/success-delete-api-key.yaml'
'500':
$ref: '../../components/responses/internal-server-error.yaml'

View File

@ -42,7 +42,7 @@
- $ref: '../../components/parameters/internal/x-participant-role.yaml'
responses:
'200':
$ref: '../../components/responses/internal/success-delete-participant.yaml'
$ref: '../../components/responses/internal/success-kick-participant.yaml'
'400':
$ref: '../../components/responses/internal/error-invalid-participant-role.yaml'
'401':

View File

@ -21,6 +21,8 @@
$ref: '../../components/responses/forbidden-error.yaml'
'404':
$ref: '../../components/responses/error-room-not-found.yaml'
'409':
$ref: '../../components/responses/internal/error-room-closed.yaml'
'422':
$ref: '../../components/responses/validation-error.yaml'
'500':
@ -48,6 +50,8 @@
$ref: '../../components/responses/forbidden-error.yaml'
'404':
$ref: '../../components/responses/internal/error-room-participant-not-found.yaml'
'409':
$ref: '../../components/responses/internal/error-room-closed.yaml'
'422':
$ref: '../../components/responses/validation-error.yaml'
'500':

View File

@ -52,10 +52,8 @@
responses:
'200':
$ref: '../components/responses/success-bulk-delete-recordings.yaml'
'204':
description: >
All specified recordings were deleted successfully.
No content is returned.
'400':
$ref: '../components/responses/error-bulk-delete-recordings.yaml'
'401':
$ref: '../components/responses/unauthorized-error.yaml'
'403':
@ -158,8 +156,8 @@
parameters:
- $ref: '../components/parameters/recording-id.yaml'
responses:
'204':
description: Recording successfully deleted. No content is returned.
'200':
$ref: '../components/responses/success-delete-recording.yaml'
'401':
$ref: '../components/responses/unauthorized-error.yaml'
'403':

View File

@ -56,11 +56,11 @@
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 any of the rooms have active meetings or recordings,
deletion behavior is determined by the provided `withMeeting` and `withRecordings` deletion policies.
If the "force" parameter is set to true, all rooms will be deleted immediately
regardless of active participants.
Depending on these policies, the rooms may be deleted/closed immediately, scheduled to be deleted/closed once the meetings end,
or the operation may fail if deletion is not permitted.
tags:
- OpenVidu Meet - Rooms
security:
@ -68,16 +68,13 @@
- accessTokenCookie: []
parameters:
- $ref: '../components/parameters/room-ids.yaml'
- $ref: '../components/parameters/force-deletion.yaml'
- $ref: '../components/parameters/meeting-deletion-policy.yaml'
- $ref: '../components/parameters/recordings-deletion-policy.yaml'
responses:
'200':
$ref: '../components/responses/success-bulk-delete-rooms.yaml'
'202':
$ref: '../components/responses/success-rooms-marked-for-deletion.yaml'
'204':
description: >
All specified rooms were successfully deleted immediately.
No content is returned.
'400':
$ref: '../components/responses/error-bulk-delete-rooms.yaml'
'401':
$ref: '../components/responses/unauthorized-error.yaml'
'403':
@ -121,13 +118,13 @@
operationId: deleteRoom
summary: Delete a room
description: |
Deletes an OpenVidu Meet room with the specified room ID.
Deletes the specified OpenVidu Meet room by its room ID.
If the room has active participants, it will be marked for deletion
and will be removed once all participants leave.
If the room has an active meeting or existing recordings,
deletion behavior is determined by the provided `withMeeting` and `withRecordings` deletion policies.
If the "force" parameter is set to true, the room will be deleted immediately
regardless of active participants.
Depending on these policies, the room may be deleted/closed immediately, scheduled to be deleted/closed once the meeting ends,
or the operation may fail if deletion is not permitted.
tags:
- OpenVidu Meet - Rooms
security:
@ -135,18 +132,21 @@
- accessTokenCookie: []
parameters:
- $ref: '../components/parameters/room-id-path.yaml'
- $ref: '../components/parameters/force-deletion.yaml'
- $ref: '../components/parameters/meeting-deletion-policy.yaml'
- $ref: '../components/parameters/recordings-deletion-policy.yaml'
responses:
'200':
$ref: '../components/responses/success-room-process-deletion.yaml'
'202':
$ref: '../components/responses/success-room-marked-for-deletion.yaml'
'204':
description: Successfully deleted the OpenVidu Meet room. No content is returned.
$ref: '../components/responses/success-room-schedule-deletion.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':
$ref: '../components/responses/error-room-process-deletion.yaml'
'422':
$ref: '../components/responses/validation-error.yaml'
'500':

View File

@ -458,7 +458,7 @@ export class RoomService {
case MeetRoomDeletionPolicyWithRecordings.CLOSE:
return {
successCode: MeetRoomDeletionSuccessCode.ROOM_CLOSED,
message: `${baseMessage} has been closed instead of deleted because it has recordings.`,
message: `${baseMessage} has been closed instead of deleted because it has recordings`,
room
};
default:
@ -478,7 +478,7 @@ export class RoomService {
case MeetRoomDeletionPolicyWithRecordings.CLOSE:
return {
successCode: MeetRoomDeletionSuccessCode.ROOM_WITH_ACTIVE_MEETING_CLOSED,
message: `${baseMessage} with active meeting has been closed instead of deleted because it has recordings.`,
message: `${baseMessage} with active meeting has been closed instead of deleted because it has recordings`,
room
};
default:
@ -498,7 +498,7 @@ export class RoomService {
case MeetRoomDeletionPolicyWithRecordings.CLOSE:
return {
successCode: MeetRoomDeletionSuccessCode.ROOM_WITH_ACTIVE_MEETING_SCHEDULED_TO_BE_CLOSED,
message: `${baseMessage} with active meeting scheduled to be closed when the meeting ends because it has recordings.`,
message: `${baseMessage} with active meeting scheduled to be closed when the meeting ends because it has recordings`,
room
};
default: