feat: Add OpenAPI Support to channels ( create, list, list.joined, info) APIs
Draft
AH
7mo ago+523-367
Description:
This PR integrates OpenAPI support into the Rocket.Chat API, migrate of Rocket.Chat API endpoints to the new OpenAPI pattern. The update includes improved API documentation, enhanced type safety, and response validation using AJV.
Key Changes:
- Implemented the new pattern and added AJV-based JSON schema validation for API.
- Uses the ExtractRoutesFromAPI utility from the TypeScript definitions to dynamically derive the routes from the endpoint specifications.
- Enabled Swagger UI integration for this API.
- Route Methods Chaining for the endpoints.
- This does not introduce any breaking changes to the endpoint logic.
Issue Reference:
Relates to #34983, part of the ongoing OpenAPI integration effort.
Testing:
- Verified that the API response schemas are correctly documented in Swagger UI.
- All tests passed without any breaking changes
$ yarn testapi -f '[Channels]'
[Channels]
✔ /channels.invite (60ms)
✔ /channels.addModerator (40ms)
✔ /channels.addModerator should fail with missing room Id (38ms)
✔ /channels.addModerator should fail with missing user Id
✔ /channels.removeModerator (72ms)
✔ /channels.removeModerator should fail on invalid room id
✔ /channels.removeModerator should fail on invalid user id (38ms)
✔ /channels.addOwner (51ms)
✔ /channels.removeOwner (61ms)
✔ /channels.kick (124ms)
✔ /channels.invite (68ms)
✔ /channels.addOwner (56ms)
✔ /channels.archive (38ms)
✔ /channels.unarchive
✔ /channels.close
✔ /channels.close
✔ /channels.open
✔ /channels.list.joined
✔ /channels.rename (97ms)
✔ /channels.addAll (812ms)
✔ /channels.addLeader (59ms)
✔ /channels.removeLeader (52ms)
✔ /channels.setJoinCode (211ms)
✔ /channels.setReadOnly (159ms)
✔ /channels.leave (93ms)
/channels.list
✔ should succesfully return a list of channels (95ms)
✔ should correctly filter channel by id (64ms)
✔ should not be succesful when user does NOT have the permission to view channels or joined rooms (392ms)
✔ should be succesful when user does NOT have the permission to view channels, but can view joined rooms (376ms)
✔ should be succesful when user does NOT have the permission to view joined rooms, but can view channels (336ms)
✔ should paginate (55ms)
/channels.counters
✔ should require auth
✔ should require a roomId
✔ should return counters for a channel with correct fields
✔ should not include deactivated users in members count (80ms)
[/channels.create]
✔ should fail when trying to use an existing room's name
- should not add guest users to more rooms than defined in the license
✔ should successfully create a channel in a team (38ms)
✔ should fail creating a channel in a team when member does not have the necessary permission
[/channels.info]
✔ creating new channel... (55ms)
✔ should fail to create the same channel twice
✔ should return channel basic structure
✔ sending a message... (165ms)
✔ REACTing with last message (73ms)
✔ STARring last message (47ms)
✔ PINning last message (61ms)
✔ should return channel structure with "lastMessage" object including pin, reactions and star(should be an array) infos (139ms)
✔ should return all channels messages where the last message of array should have the "star" array with USERS star ONLY (85ms)
✔ should return all channels messages where the last message of array should have the "star" array with USERS star ONLY even requested with count and offset params (76ms)
Additional Visibility Tests
✔ should not fetch private room info by user not part of room
✔ should not fetch private room info by user who is part of the room
✔ should fetch public room info by user who is part of the room
✔ should fetch public room info by user not part of room - because public
✔ should not fetch a private channel info inside a public team by someone part of the room
✔ should not fetch a private channel info inside a public team by someone not part of the room, but part of team (56ms)
✔ should not fetch a private channel info inside a public team by someone not part of the team
✔ should fetch a public channel info inside a public team by someone part of the room
✔ should fetch a public channel info inside a public team by someone not part of the room, but part of team
✔ should fetch a public channel info inside a public team by someone not part of the team (53ms)
✔ should fetch a public channel info inside a private team by someone part of the room
✔ should fetch a public channel info inside a private team by someone not part of the room, but part of team
✔ should not fetch a public channel info inside a private team by someone not part of team
✔ should not fetch a private channel info inside a private team by someone part of the room
✔ should not fetch a private channel info inside a private team by someone not part of the room, but part of team (40ms)
✔ should not fetch a private channel info inside a private team by someone not part of team
[/channels.online]
✔ should return an error if no query
✔ should return an error if passing an empty query
✔ should return an array with online members (619ms)
✔ should return an empty array if requesting user is not in channel (1406ms)
[/channels.files]
✔ should fail if invalid channel
✔ should fail for room type v (577ms)
✔ should succeed when searching by roomId
✔ should succeed when searching by roomId even requested with count and offset params
✔ should succeed when searching by roomName
✔ should succeed when searching by roomName even requested with count and offset params
(node:35859) [DEP0044] DeprecationWarning: The `util.isArray` API is deprecated. Please use `Array.isArray()` instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
✔ should not return thumbnails (232ms)
✔ should not return hidden files (226ms)
✔ should properly filter files by name or typeGroup (258ms)
[/channels.join]
✔ should fail if invalid channel
code-free channel
✔ should succeed when joining code-free channel without join code (43ms)
code-needed channel
without join-without-join-code permission
✔ should fail when joining code-needed channel without join code and no join-without-join-code permission (39ms)
✔ should fail when joining code-needed channel with incorrect join code and no join-without-join-code permission
✔ should succeed when joining code-needed channel with join code (44ms)
with join-without-join-code permission
✔ should succeed when joining code-needed channel without join code and with join-without-join-code permission
/channels.setDescription
✔ should set the description of the channel with a string
✔ should set the description of the channel with an empty string(remove the description) (47ms)
/channels.setTopic
✔ should set the topic of the channel with a string
✔ should set the topic of the channel with an empty string(remove the topic)
/channels.setAnnouncement
✔ should set the announcement of the channel with a string (41ms)
✔ should set the announcement of the channel with an empty string(remove the announcement) (40ms)
/channels.setPurpose
✔ should set the purpose of the channel with a string
✔ should set the announcement of channel with an empty string(remove the purpose)
/channels.history
✔ should return an array of members by channel
✔ should return an array of members by channel even requested with count and offset params
/channels.members
✔ should return an array of members by channel
✔ should return an array of members by channel even requested with count and offset params
✔ should return an filtered array of members by channel
Additional Visibility Tests
✔ should not fetch private room members by user not part of room
✔ should not fetch private room members by user who is part of the room
✔ should fetch public room members by user who is part of the room (49ms)
✔ should fetch public room members by user not part of room - because public (230ms)
✔ should not fetch a private channel members inside a public team by someone part of the room
✔ should not fetch a private channel members inside a public team by someone not part of the room, but part of team
✔ should not fetch a private channel members inside a public team by someone not part of the team
✔ should fetch a public channel members inside a public team by someone part of the room (42ms)
✔ should fetch a public channel members inside a public team by someone not part of the room, but part of team
✔ should fetch a public channel members inside a public team by someone not part of the team
✔ should fetch a public channel members inside a private team by someone part of the room
✔ should fetch a public channel members inside a private team by someone not part of the room, but part of team
✔ should not fetch a public channel members inside a private team by someone not part of team
✔ should not fetch a private channel members inside a private team by someone part of the room
✔ should not fetch a private channel members inside a private team by someone not part of the room, but part of team
✔ should not fetch a private channel members inside a private team by someone not part of team
/channels.getIntegrations
✔ should return the list of integrations of created channel and it should contain the integration created by user when the admin DOES have the permission (256ms)
✔ should return the list of integrations created by the user only (417ms)
✔ should return unauthorized error when the user does not have any integrations permissions (326ms)
Additional Visibility Tests
✔ should not fetch private room integrations by user who is part of the room (161ms)
✔ should fetch public room integrations by user who is part of the room (79ms)
✔ should fetch public room integrations by user not part of room - because public
✔ should not fetch a private channel integrations inside a public team by someone part of the room
✔ should not fetch a private channel integrations inside a public team by someone not part of the room, but part of team
✔ should not fetch a private channel integrations inside a public team by someone not part of the team
✔ should fetch a public channel integrations inside a public team by someone part of the room
✔ should fetch a public channel integrations inside a public team by someone not part of the room, but part of team
✔ should fetch a public channel integrations inside a public team by someone not part of the team
✔ should fetch a public channel integrations inside a private team by someone part of the room
✔ should fetch a public channel integrations inside a private team by someone not part of the room, but part of team
✔ should not fetch a public channel integrations inside a private team by someone not part of team
✔ should not fetch a private channel integrations inside a private team by someone part of the room
✔ should not fetch a private channel integrations inside a private team by someone not part of the room, but part of team
✔ should not fetch a private channel integrations inside a private team by someone not part of team
/channels.setCustomFields:
✔ get customFields using channels.info
✔ change customFields (41ms)
✔ get customFields using channels.info
✔ delete channels with customFields (71ms)
✔ create channel without customFields (48ms)
✔ set customFields with one nested field
✔ set customFields with multiple nested fields
✔ set customFields to empty object
✔ set customFields as a string -> should return 400
✔ delete channel with empty customFields (51ms)
/channels.setDefault
✔ should set channel as default
✔ should unset channel as default (40ms)
/channels.setType
✔ should change the type public channel to private
/channels.delete
✔ should succesfully delete a channel
✔ should fail retrieving a channel's info after it's been deleted
✔ should fail deleting a team's channel when member does not have the necessary permission in the team
✔ should fail deleting a team's channel when member has the necessary permission in the team, but not in the deleted room
✔ should successfully delete a team's channel when member has both team and channel permissions (51ms)
/channels.getAllUserMentionsByChannel
✔ should return an array of mentions by channel (557ms)
✔ should return an array of mentions by channel even requested with count and offset params (45ms)
/channels.roles
✔ /channels.invite (134ms)
✔ /channels.addModerator (98ms)
✔ /channels.addLeader (169ms)
✔ should return an array of role <-> user relationships in a channel (130ms)
/channels.moderators
✔ /channels.invite (81ms)
✔ /channels.addModerator (52ms)
✔ should return an array of moderators with rocket.cat as a moderator
Additional Visibility Tests
✔ should not fetch private room moderators by user not part of room
✔ should not fetch private room moderators by user who is part of the room
✔ should fetch public room moderators by user who is part of the room
✔ should fetch public room moderators by user not part of room - because public
✔ should not fetch a private channel moderators inside a public team by someone part of the room
✔ should not fetch a private channel moderators inside a public team by someone not part of the room, but part of team
✔ should not fetch a private channel moderators inside a public team by someone not part of the team
✔ should fetch a public channel moderators inside a public team by someone part of the room
✔ should fetch a public channel moderators inside a public team by someone not part of the room, but part of team
✔ should fetch a public channel moderators inside a public team by someone not part of the team (40ms)
✔ should fetch a public channel moderators inside a private team by someone part of the room
✔ should fetch a public channel moderators inside a private team by someone not part of the room, but part of team
✔ should not fetch a public channel moderators inside a private team by someone not part of team
✔ should not fetch a private channel moderators inside a private team by someone part of the room
✔ should not fetch a private channel moderators inside a private team by someone not part of the room, but part of team
✔ should not fetch a private channel moderators inside a private team by someone not part of team
/channels.anonymousread
✔ should return an error when the setting "Accounts_AllowAnonymousRead" is disabled (135ms)
✔ should return the messages list when the setting "Accounts_AllowAnonymousRead" is enabled (190ms)
✔ should return the messages list when the setting "Accounts_AllowAnonymousRead" is enabled even requested with count and offset params (158ms)
Additional Visibility Tests
✔ should fetch a public channel messages inside a private team by someone part of the room
✔ should fetch a public channel messages inside a private team by someone not part of the room, but part of team
✔ should not fetch a public channel messages inside a private team by someone not part of team
✔ should not fetch a public channel messages inside a private team when unauthenticated
/channels.convertToTeam
✔ should fail to convert channel if lacking create-team permission (445ms)
✔ should fail to convert channel if lacking edit-room permission (348ms)
✔ should return an error when the channel's name and id are sent as parameter
✔ should successfully convert a channel to a team when the channel's id is sent as parameter (431ms)
✔ should successfully convert a channel to a team when the channel's name is sent as parameter (83ms)
✔ should fail to convert channel without the required parameters
✔ should fail to convert channel if it's already taken
Setting: 'Use Real Name': true
✔ should return the last message user real name
✔ /channels.list.joined
✔ /channels.list.join should return empty list when member of no group (567ms)
[/channels.messages]
✔ should return an empty array of messages when inspecting a new room
✔ should return an array of messages when inspecting a room with messages
✔ should not return message when the user does NOT have the necessary permission (428ms)
✔ should return messages that mention a single user (53ms)
✔ should return messages that mention multiple users (53ms)
✔ should return messages that are starred by a specific user (49ms)
✔ should return messages that are pinned (53ms)
Additional Visibility Tests
✔ should not fetch private room messages by user not part of room
✔ should not fetch private room messages by user who is part of the room
✔ should fetch public room messages by user who is part of the room
✔ should fetch public room messages by user not part of room - because public (196ms)
✔ should not fetch a private channel messages inside a public team by someone part of the room
✔ should not fetch a private channel messages inside a public team by someone not part of the room, but part of team (52ms)
✔ should not fetch a private channel messages inside a public team by someone not part of the team
✔ should fetch a public channel messages inside a public team by someone part of the room (42ms)
✔ should fetch a public channel messages inside a public team by someone not part of the room, but part of team (47ms)
✔ should fetch a public channel messages inside a public team by someone not part of the team (40ms)
✔ should fetch a public channel messages inside a private team by someone part of the room (40ms)
✔ should fetch a public channel messages inside a private team by someone not part of the room, but part of team (66ms)
✔ should not fetch a public channel messages inside a private team by someone not part of team
✔ should not fetch a private channel messages inside a private team by someone part of the room
✔ should not fetch a private channel messages inside a private team by someone not part of the room, but part of team
✔ should not fetch a private channel messages inside a private team by someone not part of team
213 passing (42s)
1 pending
Endpoints:
Looking forward to your feedback! 🚀