Skip to content

feat: Add OpenAPI Support to subscriptions.getOne API #37085

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ahmed-n-abdeltwab wants to merge 12 commits into
base: develop
Choose a base branch
from
+170 −35
Open

feat: Add OpenAPI Support to subscriptions.getOne API #37085

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
83cf25b
feat: enhance subscriptions.getOne endpoint with openapi support
ahmed-n-abdeltwab Sep 28, 2025
a4df5df
refactor: remove subscriptions.getOne type and related from rest-typing
ahmed-n-abdeltwab Sep 28, 2025
a61c098
fix: update error response for subscriptions.getOne tests
ahmed-n-abdeltwab Sep 28, 2025
8cec5f1
Create flat-candles-walk.md
ahmed-n-abdeltwab Sep 28, 2025
07d8e66
refactor: complete the Subscriptions schema from the ISubscription
ahmed-n-abdeltwab Sep 29, 2025
5bbc104
Merge branch 'develop' into feat/openapi-subscriptions-getOne
ahmed-n-abdeltwab Sep 30, 2025
1c399b8
chore: change the department and customFields schemas to match the un…
ahmed-n-abdeltwab Oct 3, 2025
40ac948
Merge branch 'develop' into feat/openapi-subscriptions-getOne
ahmed-n-abdeltwab Oct 3, 2025
d0fdd82
Merge branch 'develop' into feat/openapi-subscriptions-getOne
ahmed-n-abdeltwab Oct 4, 2025
ee8cb7e
remove redundant logic and add minLength 1 to the Subscriptions GetOn…
ahmed-n-abdeltwab Oct 12, 2025
406d242
Merge branch 'develop' into feat/openapi-subscriptions-getOne
ahmed-n-abdeltwab Oct 12, 2025
8cf6dad
Merge branch 'develop' into feat/openapi-subscriptions-getOne
ahmed-n-abdeltwab Oct 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/flat-candles-walk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
"@rocket.chat/meteor": patch
"@rocket.chat/rest-typings": patch
---

Add OpenAPI support for the Rocket.Chat subscriptions.getOne API endpoints 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.
175 changes: 162 additions & 13 deletions apps/meteor/app/api/server/v1/subscriptions.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
import type { IRoom, ISubscription } from '@rocket.chat/core-typings';
import { Subscriptions } from '@rocket.chat/models';
import {
ajv,
validateUnauthorizedErrorResponse,
validateBadRequestErrorResponse,
isSubscriptionsGetProps,
isSubscriptionsGetOneProps,
isSubscriptionsReadProps,
isSubscriptionsUnreadProps,
} from '@rocket.chat/rest-typings';
Expand All @@ -10,6 +13,7 @@ import { Meteor } from 'meteor/meteor';
import { readMessages } from '../../../../server/lib/readMessages';
import { getSubscriptions } from '../../../../server/publications/subscription';
import { unreadMessages } from '../../../message-mark-as-unread/server/unreadMessages';
import type { ExtractRoutesFromAPI } from '../ApiClass';
import { API } from '../api';

API.v1.addRoute(
Expand Down Expand Up @@ -44,24 +48,162 @@ API.v1.addRoute(
},
);

API.v1.addRoute(
type SubscriptionsGetOne = { roomId: IRoom['_id'] };

const SubscriptionsGetOneSchema = {
type: 'object',
properties: {
roomId: {
type: 'string',
minLength: 1,
},
},
required: ['roomId'],
additionalProperties: false,
};

const isSubscriptionsGetOneProps = ajv.compile<SubscriptionsGetOne>(SubscriptionsGetOneSchema);

const subscriptionsEndpoints = API.v1.get(
'subscriptions.getOne',
{
authRequired: true,
validateParams: isSubscriptionsGetOneProps,
query: isSubscriptionsGetOneProps,
response: {
400: validateBadRequestErrorResponse,
401: validateUnauthorizedErrorResponse,
200: ajv.compile<{ subscription: ISubscription | null }>({
type: 'object',
properties: {
subscription: {
anyOf: [
{ type: 'null' },
{
type: 'object',
properties: {
_id: { type: 'string' },
open: { type: 'boolean' },
alert: { type: 'boolean' },
unread: { type: 'number' },
userMentions: { type: 'number' },
groupMentions: { type: 'number' },
ts: { type: 'string' },
rid: { type: 'string' },
u: {
type: 'object',
properties: {
_id: { type: 'string' },
username: { type: 'string' },
name: { type: 'string' },
},
},
v: {
type: 'object',
properties: {
_id: { type: 'string' },
username: { type: 'string' },
name: { type: 'string' },
status: { type: 'string' },
token: { type: 'string' },
},
},
_updatedAt: { type: 'string' },
ls: { type: 'string' },
name: { type: 'string' },
fname: { type: 'string' },
t: {
type: 'string',
enum: ['c', 'd', 'p', 'l', 'v'],
description: "Type of room. 'c' = channel, 'd' = direct, 'p' = private, 'l' = livechat, 'v' = video or voice.",
},
roles: {
type: 'array',
items: { type: 'string' },
},
lr: { type: 'string' },
tunread: {
type: 'array',
items: { type: 'string' },
},
tunreadUser: {
type: 'array',
items: { type: 'string' },
},
tunreadGroup: {
type: 'array',
items: { type: 'string' },
},
f: { type: 'boolean' },
hideUnreadStatus: { type: 'boolean', enum: [true] },
hideMentionStatus: { type: 'boolean', enum: [true] },
teamMain: { type: 'boolean' },
teamId: { type: 'string' },
broadcast: { type: 'boolean', enum: [true] },
prid: { type: 'string' },
onHold: { type: 'boolean' },
encrypted: { type: 'boolean' },
E2EKey: { type: 'string' },
E2ESuggestedKey: { type: 'string' },
unreadAlert: { type: 'string', enum: ['default', 'all', 'mentions', 'nothing'] },
archived: { type: 'boolean' },
code: { type: 'string' },
audioNotificationValue: { type: 'string' },
desktopNotifications: { type: 'string', enum: ['all', 'mentions', 'nothing'] },
mobilePushNotifications: { type: 'string', enum: ['all', 'mentions', 'nothing'] },
emailNotifications: { type: 'string', enum: ['all', 'mentions', 'nothing'] },
userHighlights: { type: 'array', items: { type: 'string' } },
blocked: { type: 'boolean' },
blocker: { type: 'string' },
autoTranslate: { type: 'boolean' },
autoTranslateLanguage: { type: 'string' },
disableNotifications: { type: 'boolean' },
muteGroupMentions: { type: 'boolean' },
ignored: {
type: 'array',
items: { type: 'string' },
},
department: {},
desktopPrefOrigin: { type: 'string', enum: ['subscription', 'user'] },
mobilePrefOrigin: { type: 'string', enum: ['subscription', 'user'] },
emailPrefOrigin: { type: 'string', enum: ['subscription', 'user'] },
customFields: {},
oldRoomKeys: {
type: 'array',
items: {
type: 'object',
properties: { e2eKeyId: { type: 'string' }, ts: { type: 'string' }, E2EKey: { type: 'string' } },
},
},
suggestedOldRoomKeys: {
type: 'array',
items: {
type: 'object',
properties: { e2eKeyId: { type: 'string' }, ts: { type: 'string' }, E2EKey: { type: 'string' } },
},
},
},
required: ['_id'],
additionalProperties: false,
},
],
},
success: {
type: 'boolean',
enum: [true],
},
},
required: ['subscription', 'success'],
additionalProperties: false,
}),
},
},
{
async get() {
const { roomId } = this.queryParams;

if (!roomId) {
return API.v1.failure("The 'roomId' param is required");
}
async function action() {
const { roomId } = this.queryParams;

return API.v1.success({
subscription: await Subscriptions.findOneByRoomIdAndUserId(roomId, this.userId),
});
},
return API.v1.success({
subscription: await Subscriptions.findOneByRoomIdAndUserId(roomId, this.userId),
});
},
);

Expand Down Expand Up @@ -110,3 +252,10 @@ API.v1.addRoute(
},
},
);

export type SubscriptionsEndpoints = ExtractRoutesFromAPI<typeof subscriptionsEndpoints>;

declare module '@rocket.chat/rest-typings' {
// eslint-disable-next-line @typescript-eslint/naming-convention, @typescript-eslint/no-empty-interface
interface Endpoints extends SubscriptionsEndpoints {}
}
3 changes: 2 additions & 1 deletion apps/meteor/tests/end-to-end/api/subscriptions.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,8 @@ describe('[Subscriptions]', () => {
.expect(400)
.expect((res) => {
expect(res.body).to.have.property('success', false);
expect(res.body).to.have.property('error', "must have required property 'roomId' [invalid-params]");
expect(res.body).to.have.property('errorType', 'error-invalid-params');
expect(res.body).to.have.property('error', "must have required property 'roomId'");
})
.end(done);
});
Expand Down
21 changes: 0 additions & 21 deletions packages/rest-typings/src/v1/subscriptionsEndpoints.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@ import Ajv from 'ajv';

type SubscriptionsGet = { updatedSince?: string };

type SubscriptionsGetOne = { roomId: IRoom['_id'] };

type SubscriptionsRead = { rid: IRoom['_id']; readThreads?: boolean } | { roomId: IRoom['_id']; readThreads?: boolean };

type SubscriptionsUnread = { roomId: IRoom['_id'] } | { firstUnreadMessage: Pick<IMessage, '_id'> };
Expand All @@ -27,19 +25,6 @@ const SubscriptionsGetSchema = {

export const isSubscriptionsGetProps = ajv.compile<SubscriptionsGet>(SubscriptionsGetSchema);

const SubscriptionsGetOneSchema = {
type: 'object',
properties: {
roomId: {
type: 'string',
},
},
required: ['roomId'],
additionalProperties: false,
};

export const isSubscriptionsGetOneProps = ajv.compile<SubscriptionsGetOne>(SubscriptionsGetOneSchema);

const SubscriptionsReadSchema = {
anyOf: [
{
Expand Down Expand Up @@ -117,12 +102,6 @@ export type SubscriptionsEndpoints = {
};
};

'/v1/subscriptions.getOne': {
GET: (params: SubscriptionsGetOne) => {
subscription: ISubscription | null;
};
};

'/v1/subscriptions.read': {
POST: (params: SubscriptionsRead) => void;
};
Expand Down
Loading