From 35524c0fbc62fedde444652b613cd972bffdd2a9 Mon Sep 17 00:00:00 2001 From: Jeffery <61447509+jeffplays2005@users.noreply.github.com> Date: Mon, 22 Jul 2024 16:28:44 +1200 Subject: [PATCH] 651 Document all backend endpoints (#673) * Add jsdoc to UserController * Tsoa generation and jsdoc for StripeWebhook endpoint * Add jsdoc for SignupController * Jsdoc for PaymentController and add fullstops * Add jsdoc for BookingController --- client/src/models/__generated__/schema.d.ts | 49 +++++++++++++++++-- .../src/middleware/__generated__/swagger.json | 48 ++++++++++++++---- .../controllers/BookingController.ts | 18 +++++++ .../controllers/PaymentController.ts | 18 +++++++ .../controllers/SignupController.ts | 6 ++- .../controllers/StripeWebhook.ts | 6 +++ .../controllers/UserController.ts | 16 ++++++ 7 files changed, 147 insertions(+), 14 deletions(-) diff --git a/client/src/models/__generated__/schema.d.ts b/client/src/models/__generated__/schema.d.ts index 657ea80a6..f4e296213 100644 --- a/client/src/models/__generated__/schema.d.ts +++ b/client/src/models/__generated__/schema.d.ts @@ -6,27 +6,38 @@ export interface paths { "/users/self": { + /** @description Fetches users additional info based on their uid. */ get: operations["GetSelf"]; }; "/users/edit-self": { + /** @description Edits the user's additional info based on their uid. */ patch: operations["EditSelf"]; }; "/users/delete-user": { + /** @description Deletes a user based on their uid. This requires an admin JWT token. */ delete: operations["DeleteUser"]; }; "/webhook": { + /** + * @description Webhook endpoint for Stripe events. + * This single endpoint is setup in the Stripe developer config to handle various events. + */ post: operations["ReceiveWebhook"]; }; "/signup": { + /** @description Signs up a user and creates a user record in the database. Also creates a JWT token for the user in AuthService. */ post: operations["Signup"]; }; "/payment/membership_prices": { + /** @description Fetches the prices of the membership products from Stripe. */ get: operations["GetMembershipPrices"]; }; "/payment/checkout_status": { + /** @description Fetches the details of a checkout session based on a stripe checkout session id. */ get: operations["GetCheckoutSessionDetails"]; }; "/payment/membership": { + /** @description Creates a checkout session for membership payment. */ post: operations["GetMembershipPayment"]; }; "/payment/booking": { @@ -38,16 +49,22 @@ export interface paths { post: operations["GetBookingPayment"]; }; "/bookings/create-bookings": { + /** @description An admin method to create bookings for a list of users within a date range. */ post: operations["CreateBookings"]; }; "/bookings": { + /** @description Fetches all bookings for a user based on their UID. */ get: operations["GetAllBookings"]; }; "/bookings/available-dates": { + /** @description Fetches all available booking dates within a date range. */ post: operations["GetAvailableDates"]; }; "/bookings/fetch-users": { - /** @description This method fetches users based on a booking date range. */ + /** + * @description This method fetches users based on a booking date range. + * This method requires an admin JWT token. + */ post: operations["FetchUsersByBookingDateRange"]; }; "/admin/bookings/make-dates-available": { @@ -469,6 +486,7 @@ export type external = Record; export interface operations { + /** @description Fetches users additional info based on their uid. */ GetSelf: { responses: { /** @description Fetched self data */ @@ -498,7 +516,9 @@ export interface operations { }; }; }; + /** @description Edits the user's additional info based on their uid. */ EditSelf: { + /** @description - The updated user additional info, note that the stripe_id is omitted. */ requestBody: { content: { "application/json": components["schemas"]["EditSelfRequestBody"]; @@ -511,7 +531,9 @@ export interface operations { }; }; }; + /** @description Deletes a user based on their uid. This requires an admin JWT token. */ DeleteUser: { + /** @description - The uid of the user to be deleted. */ requestBody: { content: { "application/json": components["schemas"]["DeleteUserRequestBody"]; @@ -526,6 +548,10 @@ export interface operations { }; }; }; + /** + * @description Webhook endpoint for Stripe events. + * This single endpoint is setup in the Stripe developer config to handle various events. + */ ReceiveWebhook: { responses: { /** @description Webhook post received */ @@ -534,7 +560,9 @@ export interface operations { }; }; }; + /** @description Signs up a user and creates a user record in the database. Also creates a JWT token for the user in AuthService. */ Signup: { + /** @description - The user's email and their user additional info. */ requestBody: { content: { "application/json": components["schemas"]["UserSignupBody"]; @@ -549,9 +577,10 @@ export interface operations { }; }; }; + /** @description Fetches the prices of the membership products from Stripe. */ GetMembershipPrices: { responses: { - /** @description Ok */ + /** @description The prices of the membership products. */ 200: { content: { "application/json": components["schemas"]["MembershipStripeProductResponse"]; @@ -559,9 +588,11 @@ export interface operations { }; }; }; + /** @description Fetches the details of a checkout session based on a stripe checkout session id. */ GetCheckoutSessionDetails: { parameters: { query: { + /** @description The id of the stripe checkout session to fetch. */ sessionId: string; }; }; @@ -580,7 +611,9 @@ export interface operations { }; }; }; + /** @description Creates a checkout session for membership payment. */ GetMembershipPayment: { + /** @description The request body containing the membership type. */ requestBody: { content: { "application/json": components["schemas"]["UserPaymentRequestModel"]; @@ -601,6 +634,7 @@ export interface operations { * the last 30 minutes (the minimum period stripe has to persist a session for) */ GetBookingPayment: { + /** @description The request body containing the date ranges for the booking. */ requestBody: { content: { "application/json": components["schemas"]["UserBookingRequestingModel"]; @@ -615,7 +649,9 @@ export interface operations { }; }; }; + /** @description An admin method to create bookings for a list of users within a date range. */ CreateBookings: { + /** @description - The date range and list of user ids to create bookings for. */ requestBody: { content: { "application/json": components["schemas"]["CreateBookingsRequestModel"]; @@ -630,6 +666,7 @@ export interface operations { }; }; }; + /** @description Fetches all bookings for a user based on their UID. */ GetAllBookings: { responses: { /** @description Found bookings */ @@ -640,7 +677,9 @@ export interface operations { }; }; }; + /** @description Fetches all available booking dates within a date range. */ GetAvailableDates: { + /** @description - The date range to check for available booking slots. */ requestBody: { content: { "application/json": components["schemas"]["AvailableDatesRequestModel"]; @@ -655,8 +694,12 @@ export interface operations { }; }; }; - /** @description This method fetches users based on a booking date range. */ + /** + * @description This method fetches users based on a booking date range. + * This method requires an admin JWT token. + */ FetchUsersByBookingDateRange: { + /** @description - The date range to check for user bookings. */ requestBody: { content: { "application/json": components["schemas"]["BookingsByDateRangeRequestModel"]; diff --git a/server/src/middleware/__generated__/swagger.json b/server/src/middleware/__generated__/swagger.json index 406ef662e..caa5e6c45 100644 --- a/server/src/middleware/__generated__/swagger.json +++ b/server/src/middleware/__generated__/swagger.json @@ -1146,6 +1146,7 @@ } } }, + "description": "Fetches users additional info based on their uid.", "security": [ { "jwt": [] @@ -1162,6 +1163,7 @@ "description": "Successful edit" } }, + "description": "Edits the user's additional info based on their uid.", "security": [ { "jwt": [] @@ -1169,11 +1171,13 @@ ], "parameters": [], "requestBody": { + "description": "- The updated user additional info, note that the stripe_id is omitted.", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EditSelfRequestBody" + "$ref": "#/components/schemas/EditSelfRequestBody", + "description": "- The updated user additional info, note that the stripe_id is omitted." } } } @@ -1200,6 +1204,7 @@ } } }, + "description": "Deletes a user based on their uid. This requires an admin JWT token.", "security": [ { "jwt": [ @@ -1209,11 +1214,13 @@ ], "parameters": [], "requestBody": { + "description": "- The uid of the user to be deleted.", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeleteUserRequestBody" + "$ref": "#/components/schemas/DeleteUserRequestBody", + "description": "- The uid of the user to be deleted." } } } @@ -1228,6 +1235,7 @@ "description": "Webhook post received" } }, + "description": "Webhook endpoint for Stripe events.\nThis single endpoint is setup in the Stripe developer config to handle various events.", "security": [], "parameters": [] } @@ -1247,14 +1255,17 @@ } } }, + "description": "Signs up a user and creates a user record in the database. Also creates a JWT token for the user in AuthService.", "security": [], "parameters": [], "requestBody": { + "description": "- The user's email and their user additional info.", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UserSignupBody" + "$ref": "#/components/schemas/UserSignupBody", + "description": "- The user's email and their user additional info." } } } @@ -1266,7 +1277,7 @@ "operationId": "GetMembershipPrices", "responses": { "200": { - "description": "Ok", + "description": "The prices of the membership products.", "content": { "application/json": { "schema": { @@ -1276,6 +1287,7 @@ } } }, + "description": "Fetches the prices of the membership products from Stripe.", "security": [], "parameters": [] } @@ -1316,6 +1328,7 @@ } } }, + "description": "Fetches the details of a checkout session based on a stripe checkout session id.", "security": [ { "jwt": [] @@ -1323,6 +1336,7 @@ ], "parameters": [ { + "description": "The id of the stripe checkout session to fetch.", "in": "query", "name": "sessionId", "required": true, @@ -1348,6 +1362,7 @@ } } }, + "description": "Creates a checkout session for membership payment.", "security": [ { "jwt": [] @@ -1355,11 +1370,13 @@ ], "parameters": [], "requestBody": { + "description": "The request body containing the membership type.", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UserPaymentRequestModel" + "$ref": "#/components/schemas/UserPaymentRequestModel", + "description": "The request body containing the membership type." } } } @@ -1391,11 +1408,13 @@ ], "parameters": [], "requestBody": { + "description": "The request body containing the date ranges for the booking.", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UserBookingRequestingModel" + "$ref": "#/components/schemas/UserBookingRequestingModel", + "description": "The request body containing the date ranges for the booking." } } } @@ -1417,6 +1436,7 @@ } } }, + "description": "An admin method to create bookings for a list of users within a date range.", "security": [ { "jwt": [ @@ -1426,11 +1446,13 @@ ], "parameters": [], "requestBody": { + "description": "- The date range and list of user ids to create bookings for.", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateBookingsRequestModel" + "$ref": "#/components/schemas/CreateBookingsRequestModel", + "description": "- The date range and list of user ids to create bookings for." } } } @@ -1452,6 +1474,7 @@ } } }, + "description": "Fetches all bookings for a user based on their UID.", "security": [ { "jwt": [ @@ -1477,6 +1500,7 @@ } } }, + "description": "Fetches all available booking dates within a date range.", "security": [ { "jwt": [ @@ -1486,11 +1510,13 @@ ], "parameters": [], "requestBody": { + "description": "- The date range to check for available booking slots.", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AvailableDatesRequestModel" + "$ref": "#/components/schemas/AvailableDatesRequestModel", + "description": "- The date range to check for available booking slots." } } } @@ -1512,7 +1538,7 @@ } } }, - "description": "This method fetches users based on a booking date range.", + "description": "This method fetches users based on a booking date range.\nThis method requires an admin JWT token.", "security": [ { "jwt": [ @@ -1522,11 +1548,13 @@ ], "parameters": [], "requestBody": { + "description": "- The date range to check for user bookings.", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BookingsByDateRangeRequestModel" + "$ref": "#/components/schemas/BookingsByDateRangeRequestModel", + "description": "- The date range to check for user bookings." } } } diff --git a/server/src/service-layer/controllers/BookingController.ts b/server/src/service-layer/controllers/BookingController.ts index 69a92fc93..0bf8e03ad 100644 --- a/server/src/service-layer/controllers/BookingController.ts +++ b/server/src/service-layer/controllers/BookingController.ts @@ -42,6 +42,11 @@ import BookingUtils from "business-layer/utils/BookingUtils" @Route("bookings") export class BookingController extends Controller { + /** + * An admin method to create bookings for a list of users within a date range. + * @param requestBody - The date range and list of user ids to create bookings for. + * @returns A list of users and timestamps that were successfully added to the booking slots. + */ @SuccessResponse("200", "Bookings successfully created") @Security("jwt", ["admin"]) @Post("create-bookings") @@ -114,6 +119,11 @@ export class BookingController extends Controller { } } + /** + * Fetches all bookings for a user based on their UID. + * @param request - The request object that includes the UserRecord. + * @returns A list of booking string dates. + */ @SuccessResponse("200", "Found bookings") @Security("jwt", ["member"]) @Get() @@ -151,6 +161,11 @@ export class BookingController extends Controller { } } + /** + * Fetches all available booking dates within a date range. + * @param requestBody - The date range to check for available booking slots. + * @returns A list of available booking dates in an array of strings. + */ @SuccessResponse("200", "Availabilities found") @Security("jwt", ["member"]) @Post("available-dates") @@ -252,6 +267,9 @@ export class BookingController extends Controller { /** * This method fetches users based on a booking date range. + * This method requires an admin JWT token. + * @param requestBody - The date range to check for user bookings. + * @returns A list of users data, booking ids and booking timestamps. */ @SuccessResponse("200", "Users found") @Security("jwt", ["admin"]) diff --git a/server/src/service-layer/controllers/PaymentController.ts b/server/src/service-layer/controllers/PaymentController.ts index 2a75a088a..9b81acdf8 100644 --- a/server/src/service-layer/controllers/PaymentController.ts +++ b/server/src/service-layer/controllers/PaymentController.ts @@ -46,6 +46,10 @@ import BookingUtils from "business-layer/utils/BookingUtils" @Route("payment") export class PaymentController extends Controller { + /** + * Fetches the prices of the membership products from Stripe. + * @returns The prices of the membership products. + */ @Get("membership_prices") public async getMembershipPrices(): Promise { const stripeService = new StripeService() @@ -103,6 +107,11 @@ export class PaymentController extends Controller { } } + /** + * Fetches the details of a checkout session based on a stripe checkout session id. + * @param sessionId The id of the stripe checkout session to fetch. + * @returns The details of the checkout session. + */ @SuccessResponse("200", "Session Fetched") @Security("jwt") @Get("checkout_status") @@ -124,6 +133,12 @@ export class PaymentController extends Controller { } } + /** + * Creates a checkout session for membership payment. + * @param request The user's record, this endpoint extracts the uid and customClaims to check for membership status. + * @param requestBody The request body containing the membership type. + * @returns The client secret of the checkout session and membership type. + */ @SuccessResponse("200", "Session created") @Security("jwt") @Post("membership") @@ -249,6 +264,9 @@ export class PaymentController extends Controller { * Creates a new booking session for the date ranges passed in, * will return any existing sessions if they have been started in * the last 30 minutes (the minimum period stripe has to persist a session for) + * @param request The user's record, the uid is used from this to identify the user. + * @param requestBody The request body containing the date ranges for the booking. + * @returns The client secret of the checkout session. */ @SuccessResponse("200", "Created booking checkout session") @Security("jwt", ["member"]) diff --git a/server/src/service-layer/controllers/SignupController.ts b/server/src/service-layer/controllers/SignupController.ts index 148e63eeb..c93c6ea1e 100644 --- a/server/src/service-layer/controllers/SignupController.ts +++ b/server/src/service-layer/controllers/SignupController.ts @@ -8,9 +8,13 @@ import { parseFirebaseError } from "business-layer/utils/FirebaseErrorParser" @Route("signup") export class UserSignup extends Controller { + /** + * Signs up a user and creates a user record in the database. Also creates a JWT token for the user in AuthService. + * @param requestBody - The user's email and their user additional info. + * @returns The JWT token and the user's UID. + */ @Post() @SuccessResponse(200, "Signup successful") - // return a JWT token at the end public async signup( @Body() requestBody: UserSignupBody ): Promise { diff --git a/server/src/service-layer/controllers/StripeWebhook.ts b/server/src/service-layer/controllers/StripeWebhook.ts index 31a1b015b..29c08debc 100644 --- a/server/src/service-layer/controllers/StripeWebhook.ts +++ b/server/src/service-layer/controllers/StripeWebhook.ts @@ -11,6 +11,12 @@ import { @Route("webhook") export class StripeWebhook extends Controller { + /** + * Webhook endpoint for Stripe events. + * This single endpoint is setup in the Stripe developer config to handle various events. + * @param request - The raw request that's passed from Stripe. + * @returns void. + */ @Post() @SuccessResponse(200, "Webhook post received") public async receiveWebhook(@Request() request: any): Promise { diff --git a/server/src/service-layer/controllers/UserController.ts b/server/src/service-layer/controllers/UserController.ts index 0ce4d464c..018e74d2c 100644 --- a/server/src/service-layer/controllers/UserController.ts +++ b/server/src/service-layer/controllers/UserController.ts @@ -22,6 +22,11 @@ import { AuthServiceClaims } from "business-layer/utils/AuthServiceClaims" @Route("users") export class UsersController extends Controller { + /** + * Fetches users additional info based on their uid. + * @param request - Takes a UserRecord and uses the UID to fetch the user's additional info. + * @returns The additionalInfo of the user. + */ @SuccessResponse("200", "Fetched self data") @Security("jwt") @Get("self") @@ -40,6 +45,12 @@ export class UsersController extends Controller { return data } + /** + * Edits the user's additional info based on their uid. + * @param request - Takes a UserRecord and uses the UID to edit the user's additional info. + * @param requestBody - The updated user additional info, note that the stripe_id is omitted. + * @returns void. + */ @SuccessResponse("200", "Successful edit") @Security("jwt") @Patch("edit-self") @@ -59,6 +70,11 @@ export class UsersController extends Controller { } } + /** + * Deletes a user based on their uid. This requires an admin JWT token. + * @param requestBody - The uid of the user to be deleted. + * @returns void. + */ @SuccessResponse("200", "Deleted user") @Security("jwt", ["admin"]) @Delete("delete-user")