Skip to content

Add Swagger documentation setup and update route parameters in controllers #289

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
Akshat-Kalra wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Add Swagger documentation setup and update route parameters in controllers #289

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d814809
Add Swagger documentation setup and update route parameters in contro…
Akshat-Kalra May 28, 2025
a9d5753
Add @nestjs/swagger dependency for API documentation
Akshat-Kalra May 28, 2025
0403237
Update packages/server/src/bootstrap.ts
Akshat-Kalra May 29, 2025
a5aa0db
Update packages/server/src/organization/organization.controller.ts
Akshat-Kalra May 29, 2025
6b959af
Refactor organization integration tests to remove optional page param…
Akshat-Kalra May 29, 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
1 change: 1 addition & 0 deletions packages/server/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@
"@nestjs/passport": "^7.1.0",
"@nestjs/platform-express": "^7.5.0",
"@nestjs/schedule": "^0.4.0",
"@nestjs/swagger": "^11.2.0",
"@nestjs/throttler": "^6.4.0",
"@nestjs/typeorm": "^11.0.0",
"@sentry/cli": "^2.36.1",
Expand Down
11 changes: 11 additions & 0 deletions packages/server/src/bootstrap.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import * as expressSession from 'express-session';
import { ApplicationConfigService } from './config/application_config.service';
import { NestExpressApplication } from '@nestjs/platform-express';
import { Chromiumly } from 'chromiumly';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
export async function bootstrap(hot: any): Promise<void> {
Expand Down Expand Up @@ -58,6 +59,16 @@ export async function bootstrap(hot: any): Promise<void> {
Chromiumly.configure({ endpoint: 'http://localhost:3004' });

app.set('trust proxy', 'loopback'); // Trust requests from the loopback address
const config = new DocumentBuilder()
.setTitle('HelpMe API')
.setDescription('HelpMe API doc')
.setVersion('1.0')
.addTag('cats')
.build();
const document = SwaggerModule.createDocument(app, config);
if (process.env.NODE_ENV === 'development') {
Copy link
Collaborator

@AdamFipke AdamFipke May 30, 2025

Choose a reason for hiding this comment

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

I would use the !isProd() helper for this since iirc something weird is set up with production's setup but isProd() is known to work

Copy link
Collaborator

@AdamFipke AdamFipke May 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

also I guess I would wrap all of these new lines of code in the same if statement block, just so that no parts of swagger load in proud just an extra precaution, even though it probably doesn't matter

SwaggerModule.setup('api', app, document);
}
await app.listen(3002);

if (hot) {
Expand Down
4 changes: 2 additions & 2 deletions packages/server/src/course/course.controller.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -714,13 +714,13 @@ export class CourseController {
}
}

@Get(':id/get_user_info/:page/:role?')
@Get(':id/get_user_info/:page')
@UseGuards(JwtAuthGuard, CourseRolesGuard, EmailVerifiedGuard)
@Roles(Role.PROFESSOR)
async getUserInfo(
@Param('id', ParseIntPipe) courseId: number,
@Param('page', ParseIntPipe) page: number,
@Param('role') role?: Role | 'staff',
@Query('role') role?: Role | 'staff',
@Query('search') search?: string,
): Promise<GetCourseUserInfoResponse> {
const pageSize = role === 'staff' ? 100 : 50;
Expand Down
8 changes: 4 additions & 4 deletions packages/server/src/organization/organization.controller.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1451,12 +1451,12 @@ export class OrganizationController {
return res.status(HttpStatus.OK).send(userInfo);
}

@Get(':oid/get_users/:page?')
@Get(':oid/get_users')
@UseGuards(JwtAuthGuard, OrganizationRolesGuard, EmailVerifiedGuard)
@Roles(OrganizationRole.ADMIN)
async getUsers(
@Param('oid', ParseIntPipe) oid: number,
@Param('page', ParseIntPipe) page: number,
@Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
@Query('search') search: string,
): Promise<OrgUser[]> {
const pageSize = 50;
Comment on lines +1454 to 1462
Copy link
Collaborator

@AdamFipke AdamFipke May 30, 2025

Choose a reason for hiding this comment

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

this new query syntax for some reason seems to be breaking the tests, I am not sure why but I would maybe try manually testing the endpoint first by opening localhost:3000/organization/users and seeing if the users load up

Copy link
Collaborator Author

@Akshat-Kalra Akshat-Kalra May 30, 2025

Choose a reason for hiding this comment

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

Yeah, I even tried the way listed on the path-to-regexp github, using this {/:param} for optionals

Expand All @@ -1468,12 +1468,12 @@ export class OrganizationController {
return await this.organizationService.getUsers(oid, page, pageSize, search);
}

@Get(':oid/get_courses/:page?')
@Get(':oid/get_courses')
@UseGuards(JwtAuthGuard, OrganizationRolesGuard, EmailVerifiedGuard)
@Roles(OrganizationRole.ADMIN)
async getCourses(
@Param('oid', ParseIntPipe) oid: number,
@Param('page', new DefaultValuePipe(-1), ParseIntPipe) page: number,
@Query('page', new DefaultValuePipe(-1), ParseIntPipe) page: number,
@Query('search') search: string,
): Promise<CourseResponse[]> {
const pageSize = 50;
Expand Down
4 changes: 2 additions & 2 deletions packages/server/test/__snapshots__/organization.integration.ts.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ exports[`Organization Integration GET /organization/:oid should return 200 and r
}
`;

exports[`Organization Integration GET /organization/:oid/get_courses/:page? should return 200 when user is an admin 1`] = `
exports[`Organization Integration GET /organization/:oid/get_courses should return 200 when user is an admin 1`] = `
[
{
"courseId": 1,
Expand Down Expand Up @@ -84,7 +84,7 @@ exports[`Organization Integration GET /organization/:oid/get_user/:uid should re
}
`;

exports[`Organization Integration GET /organization/:oid/get_users/:page? should return 200 when user is an admin 1`] = `
exports[`Organization Integration GET /organization/:oid/get_users should return 200 when user is an admin 1`] = `
[
{
"email": "user@ubc.ca",
Expand Down
4 changes: 2 additions & 2 deletions packages/server/test/organization.integration.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ describe('Organization Integration', () => {
});
});

describe('GET /organization/:oid/get_users/:page?', () => {
describe('GET /organization/:oid/get_users', () => {
it('should return 403 when user is not logged in', async () => {
const organization = await OrganizationFactory.create();
const response = await supertest().get(
Expand Down Expand Up @@ -180,7 +180,7 @@ describe('Organization Integration', () => {
});
});

describe('GET /organization/:oid/get_courses/:page?', () => {
describe('GET /organization/:oid/get_courses', () => {
it('should return 403 when user is not logged in', async () => {
const organization = await OrganizationFactory.create();
const response = await supertest().get(
Expand Down
55 changes: 47 additions & 8 deletions yarn.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2128,6 +2128,11 @@
semver "^7.3.5"
tar "^6.1.11"

"@microsoft/tsdoc@0.15.1":
version "0.15.1"
resolved "https://registry.yarnpkg.com/@microsoft/tsdoc/-/tsdoc-0.15.1.tgz#d4f6937353bc4568292654efb0a0e0532adbcba2"
integrity sha512-4aErSrCR/On/e5G2hDP0wjooqDdauzEbIq8hIkIe5pXV0rtWJZvdCEKL0ykZxex+IxIwBp0eGeV48hQN07dXtw==

"@nest-modules/mailer@^1.3.22":
version "1.3.22"
resolved "https://registry.yarnpkg.com/@nest-modules/mailer/-/mailer-1.3.22.tgz#45cf18ddde2d9ef4521ef7ecf67af01a0de020dd"
Expand Down Expand Up @@ -2230,6 +2235,11 @@
"@types/jsonwebtoken" "8.5.0"
jsonwebtoken "8.5.1"

"@nestjs/mapped-types@2.1.0":
version "2.1.0"
resolved "https://registry.yarnpkg.com/@nestjs/mapped-types/-/mapped-types-2.1.0.tgz#b9b536b7c3571567aa1d0223db8baa1a51505a19"
integrity sha512-W+n+rM69XsFdwORF11UqJahn4J3xi4g/ZEOlJNL6KoW5ygWSmBB2p0S2BZ4FQeS/NDH72e6xIcu35SfJnE8bXw==

"@nestjs/passport@^7.1.0":
version "7.1.6"
resolved "https://registry.yarnpkg.com/@nestjs/passport/-/passport-7.1.6.tgz#608bb265dfd85602aa74bbceacc012ffb2e9d25d"
Expand Down Expand Up @@ -2265,6 +2275,18 @@
jsonc-parser "3.0.0"
pluralize "8.0.0"

"@nestjs/swagger@^11.2.0":
version "11.2.0"
resolved "https://registry.yarnpkg.com/@nestjs/swagger/-/swagger-11.2.0.tgz#a1b10620a9f90c78edf897a9386dc4f3e014387e"
integrity sha512-5wolt8GmpNcrQv34tIPUtPoV1EeFbCetm40Ij3+M0FNNnf2RJ3FyWfuQvI8SBlcJyfaounYVTKzKHreFXsUyOg==
dependencies:
"@microsoft/tsdoc" "0.15.1"
"@nestjs/mapped-types" "2.1.0"
js-yaml "4.1.0"
lodash "4.17.21"
path-to-regexp "8.2.0"
swagger-ui-dist "5.21.0"

"@nestjs/testing@^10.0.0":
version "10.4.17"
resolved "https://registry.yarnpkg.com/@nestjs/testing/-/testing-10.4.17.tgz#f3a19309768261a380ac96ecddcef81231019e70"
Expand Down Expand Up @@ -3141,6 +3163,11 @@
resolved "https://registry.yarnpkg.com/@rushstack/eslint-patch/-/eslint-patch-1.11.0.tgz#75dce8e972f90bba488e2b0cc677fb233aa357ab"
integrity sha512-zxnHvoMQVqewTJr/W4pKjF0bMGiKJv1WX7bSrkl46Hg0QjESbzBROWK0Wg4RphzSOS5Jiy7eFimmM3UgMrMZbQ==

"@scarf/scarf@=1.4.0":
version "1.4.0"
resolved "https://registry.yarnpkg.com/@scarf/scarf/-/scarf-1.4.0.tgz#3bbb984085dbd6d982494538b523be1ce6562972"
integrity sha512-xxeapPiUXdZAE3che6f3xogoJPeZgig6omHEy1rIY5WVsB3H2BHNnZH+gHG6x91SCWyQCzWGsuL2Hh3ClO5/qQ==

"@schematics/schematics@0.1102.6":
version "0.1102.6"
resolved "https://registry.yarnpkg.com/@schematics/schematics/-/schematics-0.1102.6.tgz#2ce02f7c11558471628eafeb34faaa7f5ab4b22c"
Expand Down Expand Up @@ -10431,6 +10458,13 @@ js-stringify@^1.0.1, js-stringify@^1.0.2:
resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-4.0.0.tgz#19203fb59991df98e3a287050d4647cdeaf32499"
integrity sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==

js-yaml@4.1.0, js-yaml@^4.1.0:
version "4.1.0"
resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-4.1.0.tgz#c1fb65f8f5017901cdd2c951864ba18458a10602"
integrity sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==
dependencies:
argparse "^2.0.1"

js-yaml@^3.13.1:
version "3.14.1"
resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-3.14.1.tgz#dae812fdb3825fa306609a8717383c50c36a0537"
Expand All @@ -10439,13 +10473,6 @@ js-yaml@^3.13.1:
argparse "^1.0.7"
esprima "^4.0.0"

js-yaml@^4.1.0:
version "4.1.0"
resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-4.1.0.tgz#c1fb65f8f5017901cdd2c951864ba18458a10602"
integrity sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==
dependencies:
argparse "^2.0.1"

jsbn@1.1.0:
version "1.1.0"
resolved "https://registry.yarnpkg.com/jsbn/-/jsbn-1.1.0.tgz#b01307cb29b618a1ed26ec79e911f803c4da0040"
Expand Down Expand Up @@ -11032,7 +11059,7 @@ lodash.toarray@^4.4.0:
resolved "https://registry.yarnpkg.com/lodash.toarray/-/lodash.toarray-4.4.0.tgz#24c4bfcd6b2fba38bfd0594db1179d8e9b656561"
integrity sha512-QyffEA3i5dma5q2490+SgCvDN0pXLmRGSyAANuVi0HQ01Pkfr9fuoKQW8wm1wGBnJITs/mS7wQvS6VshUEBFCw==

lodash@^4, lodash@^4.17.14, lodash@^4.17.15, lodash@^4.17.19, lodash@^4.17.21, lodash@^4.17.4:
lodash@4.17.21, lodash@^4, lodash@^4.17.14, lodash@^4.17.15, lodash@^4.17.19, lodash@^4.17.21, lodash@^4.17.4:
version "4.17.21"
resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.21.tgz#679591c564c3bffaae8454cf0b3df370c3d6911c"
integrity sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==
Expand Down Expand Up @@ -13114,6 +13141,11 @@ path-to-regexp@3.3.0:
resolved "https://registry.yarnpkg.com/path-to-regexp/-/path-to-regexp-3.3.0.tgz#f7f31d32e8518c2660862b644414b6d5c63a611b"
integrity sha512-qyCH421YQPS2WFDxDjftfc1ZR5WKQzVzqsp4n9M2kQhVOo/ByahFoUNJfl58kOcEGfQ//7weFTDhm+ss8Ecxgw==

path-to-regexp@8.2.0:
version "8.2.0"
resolved "https://registry.yarnpkg.com/path-to-regexp/-/path-to-regexp-8.2.0.tgz#73990cc29e57a3ff2a0d914095156df5db79e8b4"
integrity sha512-TdrF7fW9Rphjq4RjrW0Kp2AW0Ahwu9sRGTkS6bvDi0SCwZlEZYmcfDbEsTz8RVk0EHIS/Vd1bv3JhG+1xZuAyQ==

path-type@^4.0.0:
version "4.0.0"
resolved "https://registry.yarnpkg.com/path-type/-/path-type-4.0.0.tgz#84ed01c0a7ba380afe09d90a8c180dcd9d03043b"
Expand Down Expand Up @@ -16118,6 +16150,13 @@ supports-preserve-symlinks-flag@^1.0.0:
resolved "https://registry.yarnpkg.com/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz#6eda4bd344a3c94aea376d4cc31bc77311039e09"
integrity sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==

swagger-ui-dist@5.21.0:
version "5.21.0"
resolved "https://registry.yarnpkg.com/swagger-ui-dist/-/swagger-ui-dist-5.21.0.tgz#aed230fe6e294c9470217e67697d601e3bb8eb9d"
integrity sha512-E0K3AB6HvQd8yQNSMR7eE5bk+323AUxjtCz/4ZNKiahOlPhPJxqn3UPIGs00cyY/dhrTDJ61L7C/a8u6zhGrZg==
dependencies:
"@scarf/scarf" "=1.4.0"

swr@^2.2.5:
version "2.3.3"
resolved "https://registry.yarnpkg.com/swr/-/swr-2.3.3.tgz#9d6a703355f15f9099f45114db3ef75764444788"
Expand Down
Loading