Skip to content

Conversation

@ahmed-n-abdeltwab
Copy link
Contributor

@ahmed-n-abdeltwab ahmed-n-abdeltwab commented May 14, 2025

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 '[Rooms]'     
    
    
    [Rooms]
      ✔ /rooms.get (147ms)
      ✔ /rooms.get?updatedSince (74ms)
      /rooms.saveNotification:
        ✔ /rooms.saveNotification: (154ms)
      /rooms.upload
        (node:147458) [DEP0044] DeprecationWarning: The `util.isArray` API is deprecated. Please use `Array.isArray()` instead.
        (Use `node --trace-deprecation ...` to show where the warning was created)
        ✔ don't upload a file to room with file field other than file (76ms)
        ✔ don't upload a file to room with empty file
        ✔ don't upload a file to room with more than 1 file (45ms)
        ✔ should upload a PNG file to room (1078ms)
        ✔ should upload a LST file to room (147ms)
        ✔ should upload a DRAWIO file (unknown media type) to room (125ms)
        ✔ should not allow uploading a blocked media type to a room (161ms)
        ✔ should not allow uploading an unknown media type to a room if the default one is blocked (189ms)
        ✔ should be able to get the file (72ms)
        ✔ should be able to get the file when no access to the room if setting allows it (340ms)
        ✔ should not be able to get the file when no access to the room if setting blocks (155ms)
        ✔ should be able to get the file if member and setting blocks outside access (204ms)
        ✔ should be able to get the file if not member but can access room if setting allows (366ms)
        ✔ should not be able to get the file if not member and cannot access room (275ms)
        ✔ should respect the setting with less permissions when both are true (429ms)
        ✔ should not be able to get the file without credentials
        ✔ should be able to get the file without credentials if setting allows (218ms)
        ✔ should generate thumbnail for SVG files correctly (356ms)
        ✔ should generate thumbnail for JPEG files correctly (420ms)
        ✔ should correctly save file description and properties with type e2e (352ms)
      /rooms.media
        ✔ don't upload a file to room with file field other than file (46ms)
        ✔ don't upload a file to room with empty file
        ✔ don't upload a file to room with more than 1 file (39ms)
        ✔ should upload a PNG file to room (218ms)
        ✔ should upload a LST file to room (128ms)
        ✔ should not allow uploading a blocked media type to a room (176ms)
        ✔ should be able to get the file (60ms)
        ✔ should be able to get the file when no access to the room if setting allows it (237ms)
        ✔ should not be able to get the file when no access to the room if setting blocks (184ms)
        ✔ should be able to get the file if member and setting blocks outside access (254ms)
        ✔ should not be able to get the file without credentials (47ms)
        ✔ should be able to get the file without credentials if setting allows (242ms)
        ✔ should generate thumbnail for SVG files correctly (208ms)
        ✔ should generate thumbnail for JPEG files correctly (206ms)
        ✔ should correctly save file description and properties with type e2e (208ms)
        ✔ should correctly save encrypted file (143ms)
        ✔ should correctly save encrypted file with the default media type even if another type is provided (117ms)
        ✔ should fail encrypted file upload when files encryption is disabled (187ms)
        ✔ should fail encrypted file upload on blacklisted application/octet-stream media type (162ms)
        /rooms.media - Max allowed size
          ✔ should allow uploading a file with description under the max character limit (306ms)
          ✔ should not allow uploading a file with description over the max character limit (71ms)
      /rooms.favorite
        ✔ should favorite the room when send favorite: true by roomName
        ✔ should unfavorite the room when send favorite: false by roomName
        ✔ should favorite the room when send favorite: true by roomId
        ✔ should unfavorite room when send favorite: false by roomId
        ✔ should return an error when send an invalid room
      /rooms.nameExists
        ✔ should return 401 unauthorized when user is not logged in
        ✔ should return true if this room name exists
        ✔ should return false if this room name does not exist
        ✔ should return an error when the require parameter (roomName) is not provided
      [/rooms.cleanHistory]
        ✔ should return success when send a valid public channel (53ms)
        ✔ should not count hidden or deleted messages when limit param is not sent (801ms)
        ✔ should not count hidden or deleted messages when limit param is sent (117ms)
        ✔ should successfully delete an image and thumbnail from public channel
        ✔ should remove only files and file attachments when filesOnly is set to true (337ms)
        ✔ should not remove quote attachments when filesOnly is set to true (323ms)
        ✔ should return success when send a valid private channel
        ✔ should return success when send a valid Direct Message channel
        ✔ should return not allowed error when try deleting messages with user without permission (40ms)
        test user is not part of room
          ✔ should return an error when the user with right privileges is not part of the room
      [/rooms.info]
        ✔ should return the info about the created channel correctly searching by roomId
        ✔ should return the info about the created channel correctly searching by roomName
        ✔ should return the info about the created group correctly searching by roomId (43ms)
        ✔ should return the info about the created group correctly searching by roomName
        ✔ should return the info about the created DM correctly searching by roomId
        ✔ should not return parent & team for room thats not on a team nor is a discussion
        with team and parent data
          ✔ should return the channel info, team and parent info
          ✔ should return the dicsussion room info and parent info
          ✔ should not return parent info for the main room of the team
          ✔ should not return team for room outside team
          ✔ should return the parent for discussion outside team
          ✔ should return the parent for a discussion created from team main room
      [/rooms.leave]
        ✔ should return an Error when trying leave a DM room
        ✔ should return an Error when trying to leave a public channel and you are the last owner (53ms)
        ✔ should return an Error when trying to leave a private group and you are the last owner
        ✔ should return an Error when trying to leave a public channel and not have the necessary permission(leave-c) (198ms)
        ✔ should return an Error when trying to leave a private group and not have the necessary permission(leave-p) (207ms)
        ✔ should leave the public channel when the room has at least another owner and the user has the necessary permission(leave-c) (359ms)
        ✔ should leave the private group when the room has at least another owner and the user has the necessary permission(leave-p) (343ms)
      /rooms.createDiscussion
        ✔ should throw an error when the user tries to create a discussion and the feature is disabled (283ms)
        ✔ should throw an error when the user tries to create a discussion and does not have at least one of the required permissions (972ms)
        ✔ should throw an error when the user tries to create a discussion without the required parameter "prid"
        ✔ should throw an error when the user tries to create a discussion without the required parameter "t_name"
        ✔ should throw an error when the user tries to create a discussion with the required parameter invalid "users"(different from an array)
        ✔ should throw an error when the user tries to create a discussion with the channel's id invalid
        ✔ should throw an error when the user tries to create a discussion with the message's id invalid
        ✔ should create a discussion successfully when send only the required parameters (68ms)
        ✔ should create a discussion successfully when send the required parameters plus the optional parameter "reply" (120ms)
        ✔ should create a discussion successfully when send the required parameters plus the optional parameter "users" (127ms)
        ✔ should create a discussion successfully when send the required parameters plus the optional parameter "pmid" (132ms)
        it should create a *private* discussion if the parent channel is public and inside a private team
          ✔ should create a team (60ms)
          ✔ should add the public channel to the team
          ✔ should create a private discussion inside the public channel (65ms)
      /rooms.getDiscussions
        ✔ should throw an error when the user tries to gets a list of discussion without a required parameter "roomId"
        ✔ should throw an error when the user tries to gets a list of discussion and he cannot access the room (358ms)
        ✔ should return a list of discussions with ONE discussion
      [/rooms.autocomplete.channelAndPrivate]
        ✔ should return an error when the required parameter "selector" is not provided
        ✔ should return the rooms to fill auto complete
      [/rooms.autocomplete.channelAndPrivate.withPagination]
        ✔ should return an error when the required parameter "selector" is not provided
        ✔ should return the rooms to fill auto complete (63ms)
        ✔ should return the rooms to fill auto complete even requested with count and offset params
      [/rooms.autocomplete.availableForTeams]
        ✔ should return the rooms to fill auto complete
        ✔ should return the filtered rooms to fill auto complete
      [/rooms.autocomplete.adminRooms]
        - should return an error when the required parameter "selector" is not provided
        ✔ should return the rooms to fill auto complete (44ms)
        ✔ should return the rooms to fill auto complete
      /rooms.adminRooms
        ✔ should throw an error when the user tries to gets a list of discussion and he cannot access the room (362ms)
        ✔ should return a list of admin rooms (41ms)
        ✔ should return a list of admin rooms even requested with count and offset params
        ✔ should search the list of admin rooms using non-latin characters when UI_Allow_room_names_with_special_chars setting is toggled (164ms)
        ✔ should search the list of admin rooms using latin characters only when UI_Allow_room_names_with_special_chars setting is disabled (151ms)
        ✔ should filter by only rooms types (44ms)
        ✔ should filter by only name
        ✔ should filter by type and name at the same query
        ✔ should return an empty array when filter by wrong type and correct room name
        ✔ should return an array sorted by "ts" property
      update group dms name
        ✔ should update group name if user changes username (525ms)
        ✔ should update group name if user changes name (527ms)
      /rooms.delete
        ✔ should throw an error when roomId is not provided
        ✔ should delete a room when the request is correct (55ms)
        ✔ should throw an error when the room id doesn exist
      rooms.saveRoomSettings
        ✔ should update the room settings (742ms)
        ✔ should have reflected on rooms.info
        ✔ should be able to update the discussion name with spaces (60ms)
        ✔ should mark a room as favorite (42ms)
        ✔ should not mark a room as favorite when room is not a default room (58ms)
        ✔ should update the team sidepanel items to channels and discussions (45ms)
        ✔ should throw error when updating team sidepanel with incorrect items
        ✔ should throw error when updating team sidepanel with more than 2 items
        ✔ should throw error when updating team sidepanel with duplicated items (42ms)
      rooms.images
        ✔ should return an error when user is not logged in
        ✔ should return an error when the required parameter "roomId" is not provided
        ✔ should return an error when the required parameter "roomId" is not a valid room
        ✔ should return an error when room is valid but user is not part of it (125ms)
        ✔ should return an empty array when room is valid and user is part of it but there are no images (108ms)
        ✔ should return an array of images when room is valid and user is part of it and there are images (339ms)
        ✔ should return multiple images when room is valid and user is part of it and there are multiple images (521ms)
        ✔ should allow to filter images passing the startingFromId parameter (657ms)
      /rooms.muteUser
        ✔ should invite rocket.cat user to room (43ms)
        ✔ should mute the rocket.cat user
        ✔ should contain rocket.cat user in mute list
      /rooms.unmuteUser
        ✔ should unmute the rocket.cat user in read-only room
        ✔ should contain rocket.cat user in unmute list
      /rooms.export
        ✔ should fail exporting room as file if dates are incorrectly provided
        ✔ should fail exporting room as file if no roomId is provided
        ✔ should fail exporting room as file if no type is provided
        ✔ should fail exporting room as file if fromDate is after toDate (incorrect date interval)
        ✔ should fail exporting room as file if invalid roomId is provided
        ✔ should fail exporting room as file if no format is provided
        ✔ should fail exporting room as file if an invalid format is provided
        ✔ should fail exporting room as file if an invalid type is provided
        ✔ should succesfully export room as file
        ✔ should succesfully export room as file even if no dates are provided (66ms)
        ✔ should fail exporting room via email if target users AND target emails are NOT provided (48ms)
        ✔ should fail exporting room via email if no target e-mails are provided
        ✔ should fail exporting room via email if no target users or e-mails params are provided
        ✔ should fail exporting room via email if no messages are provided
        ✔ should succesfully export room via email (51ms)
      /rooms.isMember
        ✔ should return error if room not found
        ✔ should return error if user not found with the given userId
        ✔ should return error if user not found with the given username
        ✔ should return success with isMember=true if given userId is a member of the channel (46ms)
        ✔ should return success with isMember=true if given username is a member of the channel
        ✔ should return success with isMember=false if user is not a member of the channel
        ✔ should return success with isMember=true if given userId is a member of the group
        ✔ should return success with isMember=true if given username is a member of the group
        ✔ should return success with isMember=false if user is not a member of the group
        ✔ should return unauthorized if caller cannot access the group
        ✔ should return success with isMember=true if given userId is a member of the DM
        ✔ should return success with isMember=true if given username is a member of the DM
        ✔ should return success with isMember=false if user is not a member of the DM
        ✔ should return unauthorized if caller cannot access the DM
      /rooms.open
        ✔ should open the room
        ✔ should fail if roomId is not provided
      [/rooms.membersOrderedByRole]
        ✔ should return a list of members ordered by owner, leader, moderator, then members by default (46ms)
        ✔ should support sorting by role in descending priority
        ✔ should support pagination
        ✔ should return matched members when using filter param (288ms)
        ✔ should return empty list if no matches (e.g., filter by status that no one has)
        ✔ should support custom sorting by username descending
        ✔ should not be affected by custom roles when sorting
        Sort by user status
          ✔ should sort by user status after user role
        Additional Visibility Tests
          ✔ should not fetch private room members by user not part of room
          ✔ should 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
          ✔ should fetch public room members by user not part of room - because public (203ms)
          ✔ should 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 
          ✔ 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 fetch a private channel members inside a private team by someone part of the room (47ms)
          ✔ 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
      /rooms.hide
        ✔ should hide the room
        ✔ should be already hidden
        ✔ should fail if roomId is not provided
        ✔ should return 401 if user is not logged in
        ✔ should return forbidden if user does not have access to the room
      /rooms.roles
        ✔ should get room roles
    
    
    206 passing (59s)
    1 pending
        

Endpoints:

Looking forward to your feedback! 🚀

@dionisio-bot
Copy link
Contributor

dionisio-bot bot commented May 14, 2025

Looks like this PR is not ready to merge, because of the following issues:

  • This PR is missing the 'stat: QA assured' label
  • This PR is missing the required milestone or project

Please fix the issues and try again

If you have any trouble, please check the PR guidelines

@changeset-bot
Copy link

changeset-bot bot commented May 14, 2025

🦋 Changeset detected

Latest commit: dbacf9e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 39 packages
Name Type
@rocket.chat/meteor Patch
@rocket.chat/rest-typings Patch
@rocket.chat/api-client Patch
@rocket.chat/core-services Patch
@rocket.chat/ddp-client Patch
@rocket.chat/http-router Patch
@rocket.chat/models Patch
@rocket.chat/ui-contexts Patch
@rocket.chat/web-ui-registration Patch
@rocket.chat/account-service Patch
@rocket.chat/authorization-service Patch
@rocket.chat/ddp-streamer Patch
@rocket.chat/stream-hub-service Patch
@rocket.chat/omnichannel-services Patch
@rocket.chat/presence Patch
rocketchat-services Patch
@rocket.chat/omnichannel-transcript Patch
@rocket.chat/presence-service Patch
@rocket.chat/queue-worker Patch
@rocket.chat/network-broker Patch
@rocket.chat/livechat Patch
@rocket.chat/mock-providers Patch
@rocket.chat/cron Patch
@rocket.chat/instance-status Patch
@rocket.chat/omni-core Patch
@rocket.chat/omni-core-ee Patch
@rocket.chat/uikit-playground Patch
@rocket.chat/fuselage-ui-kit Patch
@rocket.chat/gazzodown Patch
@rocket.chat/ui-avatar Patch
@rocket.chat/ui-client Patch
@rocket.chat/ui-video-conf Patch
@rocket.chat/ui-voip Patch
@rocket.chat/core-typings Patch
@rocket.chat/apps Patch
@rocket.chat/freeswitch Patch
@rocket.chat/model-typings Patch
@rocket.chat/license Patch
@rocket.chat/pdf-worker Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@kody-ai
Copy link

kody-ai bot commented May 14, 2025

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration
Interacting with Kody
  • Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

  • Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration
Review Options

The following review options are enabled or disabled:

Options Enabled
Security
Code Style
Kody Rules
Refactoring
Error Handling
Maintainability
Potential Issues
Documentation And Comments
Performance And Optimization
Breaking Changes

Access your configuration settings here.

@CLAassistant
Copy link

CLAassistant commented May 14, 2025

CLA assistant check
All committers have signed the CLA.

@ahmed-n-abdeltwab ahmed-n-abdeltwab requested review from a team as code owners May 14, 2025 16:38
@kody-ai
Copy link

kody-ai bot commented May 14, 2025

Kody Review Complete

Great news! 🎉
No issues were found that match your current review configurations.

Keep up the excellent work! 🚀

Kody Guide: Usage and Configuration
Interacting with Kody
  • Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

  • Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration
Review Options

The following review options are enabled or disabled:

Options Enabled
Security
Code Style
Kody Rules
Refactoring
Error Handling
Maintainability
Potential Issues
Documentation And Comments
Performance And Optimization
Breaking Changes

Access your configuration settings here.

@kody-ai
Copy link

kody-ai bot commented May 14, 2025

Kody Review Complete

Great news! 🎉
No issues were found that match your current review configurations.

Keep up the excellent work! 🚀

Kody Guide: Usage and Configuration
Interacting with Kody
  • Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

  • Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration
Review Options

The following review options are enabled or disabled:

Options Enabled
Security
Code Style
Kody Rules
Refactoring
Error Handling
Maintainability
Potential Issues
Documentation And Comments
Performance And Optimization
Breaking Changes

Access your configuration settings here.

@kody-ai
Copy link

kody-ai bot commented May 15, 2025

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration
Interacting with Kody
  • Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

  • Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration
Review Options

The following review options are enabled or disabled:

Options Enabled
Security
Code Style
Kody Rules
Refactoring
Error Handling
Maintainability
Potential Issues
Documentation And Comments
Performance And Optimization
Breaking Changes

Access your configuration settings here.

@ahmed-n-abdeltwab ahmed-n-abdeltwab requested a review from a team as a code owner August 6, 2025 10:54
@ahmed-n-abdeltwab ahmed-n-abdeltwab marked this pull request as draft August 6, 2025 10:54
@ahmed-n-abdeltwab ahmed-n-abdeltwab marked this pull request as ready for review August 7, 2025 16:27
@ahmed-n-abdeltwab ahmed-n-abdeltwab requested a review from a team as a code owner August 7, 2025 16:27
@ahmed-n-abdeltwab
Copy link
Contributor Author

@cardoso, @ggazzo this API is Ready for review whenever you have time

Copy link
Member

@cardoso cardoso left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ggazzo 👍

@ahmed-n-abdeltwab
Copy link
Contributor Author

Looks fine

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants