chore: Add OpenAPI Support to Statistics API by ahmed-n-abdeltwab · Pull Request #35692 · RocketChat/Rocket.Chat

ahmed-n-abdeltwab · 2025-04-03T06:09:41Z

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.
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 '[Statistics]'


  [Statistics]
    [/statistics]
      ✔ should return an error when the user does not have the necessary permission (248ms)
      ✔ should return an object with the statistics (224ms)
      ✔ should update the statistics when is provided the "refresh:true" query parameter (338ms)
    [/statistics.list]
      ✔ should return an error when the user does not have the necessary permission (273ms)
      ✔ should return an array with the statistics (394ms)
      ✔ should return an array with the statistics even requested with count and offset params (202ms)


  6 passing (2s)

Endpoints:

statistics:
- Get Last Statistics

Statistics Telemetry

Looking forward to your feedback! 🚀

Description

This pull request introduces OpenAPI support to the statistics API in the ahmed-n-abdeltwab/Rocket.Chat repository. The changes are made in the apps/meteor/app/api/server/v1/stats.ts file. The update involves refactoring the statistics API routes to incorporate typed validation using ajv schema definitions. This enhancement aims to improve type safety and request validation while preserving the existing functionality of the API. The changes are proposed from the feat/OpenAPI branch to be merged into the develop branch.

dionisio-bot · 2025-04-03T06:09:45Z

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 · 2025-04-03T06:09:45Z

🦋 Changeset detected

Latest commit: b3f9142

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

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

CLAassistant · 2025-04-03T06:09:47Z

All committers have signed the CLA.

ahmed-n-abdeltwab · 2025-04-03T06:12:25Z

@kody start-review

kody-ai · 2025-04-03T06:12:37Z

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.

apps/meteor/app/api/server/v1/stats.ts

ahmed-n-abdeltwab · 2025-04-03T14:48:24Z

I usually run yarn lint -- --fix before committing, but this time, after running it, I noticed that it applied fixes across the entire project. As a result, when I added my file to Git and committed, it unintentionally included changes from the entire codebase.

To resolve this, I reverted the unintended changes and manually fixed only my file using the following command:

npx eslint --parser @typescript-eslint/parser --parser-options "project: ['./tsconfig.base.json']" apps/meteor/app/api/server/v1/stats.ts --fix

This ensured that only the intended file was fixed and committed correctly.
Should I report this as an issue, or should we wait to see if it happens again?

ahmed-n-abdeltwab · 2025-04-03T15:20:00Z

@kody start-review

kody-ai · 2025-04-03T15:21:27Z

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.

ahmed-n-abdeltwab · 2025-04-03T18:17:06Z

@kody start-review

kody-ai · 2025-04-03T18:18:13Z

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 · 2025-04-03T18:34:08Z

@kody start-review

kody-ai · 2025-04-03T18:35:47Z

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.

ahmed-n-abdeltwab · 2025-04-04T04:23:00Z

@kody start-review

ahmed-n-abdeltwab · 2025-04-04T04:28:58Z

Hi @ggazzo,

I've refactored the statistics endpoints to improve:

Code organization (separated handlers from route configs)
Schema validation (additionalProperties: false, added descriptions)
Documentation (OpenAPI compatibility)

Could you please review these changes and share your feedback.

ggazzo

there is no reason to "over-optimize" the code.

keep the functions and schemas directly in the endpoint declarations.

this way TypeScript can infer things like this, and in this case, since we have several schemas and actions, it is better to understand which one belongs what

ahmed-n-abdeltwab · 2025-04-04T16:45:02Z

there is no reason to "over-optimize" the code.

keep the functions and schemas directly in the endpoint declarations.

this way TypeScript can infer things like this, and in this case, since we have several schemas and actions, it is better to understand which one belongs what

I see your point! My thought was to improve maintainability by keeping things modular, but I can inline them if that's the preferred structure. Let me know if you want any adjustments!

ahmed-n-abdeltwab · 2025-04-04T17:18:37Z

@kody start-review

ahmed-n-abdeltwab · 2025-04-04T18:41:08Z

Hey @ggazzo, I’ve made the recent changes you suggested by keeping the functions and schemas inline within the endpoint declarations. I also added types for the query parameters and body, and fixed the schema naming to be uppercase. Let me know if you have any feedback!

ggazzo · 2025-04-04T21:03:41Z

@ahmed-n-abdeltwab how is your editor configured? we dont need to run the ci to realize we have typescript errors

ahmed-n-abdeltwab · 2025-04-04T21:34:01Z

@ahmed-n-abdeltwab how is your editor configured? we dont need to run the ci to realize we have typescript errors

I'm using Vim as my editor. With default configuration

ahmed-n-abdeltwab · 2025-07-10T15:31:01Z

@ahmed-n-abdeltwab seems tests are failing, but could be unrelated, I'll rerun them.

Thank you so much. By the way, I looked at it before pinging you, and it passed the statistics test, I saw it.

ahmed-n-abdeltwab · 2025-07-15T14:15:48Z

im going to update this pr

apps/meteor/app/statistics/server/lib/getAppsStatistics.ts

packages/core-services/src/types/ITelemetryEvent.ts

packages/core-typings/src/IStats.ts

coderabbitai · 2025-09-27T13:22:48Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

ahmed-n-abdeltwab · 2026-02-22T16:52:23Z

apps/meteor/app/statistics/server/functions/getLastStatistics.ts

+
+	const stats = await Statistics.findLast();
+
+	if (!stats) {
+		return stats;
+	}
+
+	// Ensure dates are formatted consistently as strings (same as when refresh=true)
+	// This prevents JSON schema validation errors where Date | string types cause ambiguity
+	if (stats.migration) {
+		stats.migration = {
+			...stats.migration,
+			buildAt: formatDate(stats.migration.buildAt),
+			lockedAt: formatDate(stats.migration.lockedAt),
+		};
+	}
+
+	// Format createdAt if it's a Date object
+	if (stats.createdAt instanceof Date) {
+		stats.createdAt = stats.createdAt.toString();
+	}
+
+	return stats;


The date props coming from the database are causing AJV validation errors because they aren't formatted as strings. As a work around fix, I’ve added a check in this function to ensure the dates passed to the controller are properly formatted. no edit or change was made in the logic

ahmed-n-abdeltwab · 2026-02-22T16:55:28Z

apps/meteor/app/statistics/server/lib/statistics.ts

@@ -27,6 +27,8 @@ import {
 	Users,


In this file, the fix ensures a default value is passed when props are undefined. This aligns with the database interface and prevents unpredictable values from being passed. no edit or change was made in the logic

ahmed-n-abdeltwab · 2026-02-22T16:58:01Z

packages/core-typings/src/IStats.ts

 	federatedUsers: number;
 	lastLogin: string;
-	lastMessageSentAt: Date | undefined;
+	lastMessageSentAt: string | undefined;


The use of Date objects should be forbidden due to JSON serialization issues. Additionally, AJV is configured to fail when parsing Date types, as it expects string-formatted timestamps. the right change was made to fix this bug

ahmed-n-abdeltwab · 2026-02-22T17:02:36Z

packages/core-typings/src/IStats.ts

 	onHoldEnabled: boolean;
 	emailInboxes: number;
-	BusinessHours: { [key: string]: number | string };
+	BusinessHours: { total: number; strategy: string };


Using union types (the OR operator) can be dangerous because Typia interprets them as oneOf. AJV treats oneOf strictly: exactly one schema must match. If both are true or both are false, validation fails. To ensure type safety and predictable behavior, it is recommended to use explicit types. If a developer chooses to use a union type, they must manually handle any potential regressions

ahmed-n-abdeltwab · 2026-02-23T18:42:36Z

thanks for the unconcurrency test #38939 i feel like this is going to work

…ts by migrating to a modern chained route definition syntax and utilizing shared AJV schemas for validation to enhance API documentation and ensure type safety through response validation.

ahmed-n-abdeltwab · 2026-02-24T12:06:34Z

The CI is failing because of the /api/v1/autotranslate.translateMessage endpoint. I have migrated it to the new pattern and discovered a bug in it. Both the migration and the bug fix are included in this PR: #38978

ahmed-n-abdeltwab changed the title ~~feat: Add OpenAPI Support to stats api (#34983)~~ feat: Add OpenAPI Support to stats api Apr 3, 2025

kody-ai bot reviewed Apr 3, 2025

View reviewed changes

apps/meteor/app/api/server/v1/stats.ts Show resolved Hide resolved

ahmed-n-abdeltwab requested a review from ggazzo April 3, 2025 15:32

ggazzo modified the milestones: 7.6.0, Short-term Apr 4, 2025

ggazzo self-assigned this Apr 4, 2025

ggazzo requested changes Apr 4, 2025

View reviewed changes

ahmed-n-abdeltwab requested a review from ggazzo April 4, 2025 17:18

ahmed-n-abdeltwab marked this pull request as draft July 15, 2025 14:15

This was referenced Jul 17, 2025

[NOMERGE] feat: openapi migration progress #36458

Closed

[NOMERGE] feat: openapi migration progress RocketChat/Rocket.Chat-Open-API#150

Draft

ahmed-n-abdeltwab marked this pull request as ready for review July 18, 2025 03:29

ahmed-n-abdeltwab marked this pull request as draft August 5, 2025 06:53

ahmed-n-abdeltwab commented Aug 5, 2025

View reviewed changes

apps/meteor/app/statistics/server/lib/getAppsStatistics.ts Show resolved Hide resolved

ahmed-n-abdeltwab commented Aug 5, 2025

View reviewed changes

packages/core-services/src/types/ITelemetryEvent.ts Show resolved Hide resolved

ahmed-n-abdeltwab commented Aug 5, 2025

View reviewed changes

packages/core-typings/src/IStats.ts Outdated Show resolved Hide resolved

ahmed-n-abdeltwab force-pushed the feat/OpenAPI branch 5 times, most recently from ae58c51 to 9539a0a Compare February 22, 2026 16:48

ahmed-n-abdeltwab commented Feb 22, 2026

View reviewed changes

ahmed-n-abdeltwab force-pushed the feat/OpenAPI branch from 7a4ded4 to 3b1c650 Compare February 23, 2026 19:01

ahmed-n-abdeltwab changed the title ~~feat: Add OpenAPI Support to Statistics API~~ chore: Add OpenAPI Support to Statistics API Feb 24, 2026

dionisio-bot bot added stat: conflict and removed stat: conflict labels Feb 24, 2026

chore: Add OpenAPI support for the Rocket.Chat Statistics API endpoin…

e1f7237

…ts by migrating to a modern chained route definition syntax and utilizing shared AJV schemas for validation to enhance API documentation and ensure type safety through response validation.

ahmed-n-abdeltwab force-pushed the feat/OpenAPI branch from a9bb7e8 to e1f7237 Compare February 24, 2026 09:09

ahmed-n-abdeltwab and others added 2 commits February 25, 2026 11:42

Merge branch 'develop' into feat/OpenAPI

bcaca30

Merge branch 'develop' into feat/OpenAPI

b3f9142

Conversation

ahmed-n-abdeltwab commented Apr 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

dionisio-bot bot commented Apr 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Apr 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

CLAassistant commented Apr 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ahmed-n-abdeltwab commented Apr 3, 2025

Uh oh!

kody-ai bot commented Apr 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review Completed! 🔥

Uh oh!

Uh oh!

ahmed-n-abdeltwab commented Apr 3, 2025

Uh oh!

ahmed-n-abdeltwab commented Apr 3, 2025

Uh oh!

kody-ai bot commented Apr 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Kody Review Complete

Uh oh!

ahmed-n-abdeltwab commented Apr 3, 2025

Uh oh!

kody-ai bot commented Apr 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review Completed! 🔥

Uh oh!

ahmed-n-abdeltwab commented Apr 3, 2025

Uh oh!

kody-ai bot commented Apr 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Kody Review Complete

Uh oh!

ahmed-n-abdeltwab commented Apr 4, 2025

Uh oh!

ahmed-n-abdeltwab commented Apr 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ggazzo left a comment

Choose a reason for hiding this comment

Uh oh!

ahmed-n-abdeltwab commented Apr 4, 2025

Uh oh!

ahmed-n-abdeltwab commented Apr 4, 2025

Uh oh!

ahmed-n-abdeltwab commented Apr 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ggazzo commented Apr 4, 2025

Uh oh!

ahmed-n-abdeltwab commented Apr 4, 2025

Uh oh!

ahmed-n-abdeltwab commented Jul 10, 2025

Uh oh!

ahmed-n-abdeltwab commented Jul 15, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot commented Sep 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

ahmed-n-abdeltwab Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ahmed-n-abdeltwab Feb 22, 2026

Choose a reason for hiding this comment

Uh oh!

ahmed-n-abdeltwab Feb 22, 2026

ahmed-n-abdeltwab commented Apr 3, 2025 •

edited

Loading

dionisio-bot bot commented Apr 3, 2025 •

edited

Loading

changeset-bot bot commented Apr 3, 2025 •

edited

Loading

CLAassistant commented Apr 3, 2025 •

edited

Loading

kody-ai bot commented Apr 3, 2025 •

edited

Loading

kody-ai bot commented Apr 3, 2025 •

edited

Loading

kody-ai bot commented Apr 3, 2025 •

edited

Loading

kody-ai bot commented Apr 3, 2025 •

edited

Loading

ahmed-n-abdeltwab commented Apr 4, 2025 •

edited

Loading

ahmed-n-abdeltwab commented Apr 4, 2025 •

edited

Loading

coderabbitai bot commented Sep 27, 2025 •

edited

Loading

ahmed-n-abdeltwab Feb 22, 2026 •

edited

Loading

ahmed-n-abdeltwab commented Feb 23, 2026 •

edited

Loading