From ac43d90d533fb04be969ad9e9c94caef106975ad Mon Sep 17 00:00:00 2001 From: Keith Williams Date: Wed, 25 Sep 2024 15:09:53 -0300 Subject: [PATCH] feat: Improve API v2 docs (#16818) * feat: Improve API v2 docs * Consistency * Made the descriptions complete sentences with period * Update apps/api/v2/src/ee/schedules/schedules_2024_06_11/controllers/schedules.controller.ts --- .../controllers/calendars.controller.ts | 2 ++ .../controllers/schedules.controller.ts | 5 ---- .../controllers/schedules.controller.ts | 27 ++++++++++++------- 3 files changed, 19 insertions(+), 15 deletions(-) diff --git a/apps/api/v2/src/ee/calendars/controllers/calendars.controller.ts b/apps/api/v2/src/ee/calendars/controllers/calendars.controller.ts index 452f011b94..b12589e1fa 100644 --- a/apps/api/v2/src/ee/calendars/controllers/calendars.controller.ts +++ b/apps/api/v2/src/ee/calendars/controllers/calendars.controller.ts @@ -68,6 +68,7 @@ export class CalendarsController { @Post("/ics-feed/save") @UseGuards(ApiAuthGuard) + @ApiOperation({ summary: "Save an ICS feed" }) async createIcsFeed( @GetUser("id") userId: number, @GetUser("email") userEmail: string, @@ -78,6 +79,7 @@ export class CalendarsController { @Get("/ics-feed/check") @UseGuards(ApiAuthGuard) + @ApiOperation({ summary: "Check an ICS feed" }) async checkIcsFeed(@GetUser("id") userId: number): Promise { return await this.icsFeedService.check(userId); } diff --git a/apps/api/v2/src/ee/schedules/schedules_2024_04_15/controllers/schedules.controller.ts b/apps/api/v2/src/ee/schedules/schedules_2024_04_15/controllers/schedules.controller.ts index 54a6d7034b..803fb9c880 100644 --- a/apps/api/v2/src/ee/schedules/schedules_2024_04_15/controllers/schedules.controller.ts +++ b/apps/api/v2/src/ee/schedules/schedules_2024_04_15/controllers/schedules.controller.ts @@ -57,11 +57,6 @@ export class SchedulesController_2024_04_15 { @Get("/default") @Permissions([SCHEDULE_READ]) - @ApiResponse({ - status: 200, - description: "Returns the default schedule", - type: GetDefaultScheduleOutput_2024_04_15, - }) async getDefaultSchedule( @GetUser() user: UserWithProfile ): Promise { diff --git a/apps/api/v2/src/ee/schedules/schedules_2024_06_11/controllers/schedules.controller.ts b/apps/api/v2/src/ee/schedules/schedules_2024_06_11/controllers/schedules.controller.ts index 2b22b66d5c..a76bc40bdf 100644 --- a/apps/api/v2/src/ee/schedules/schedules_2024_06_11/controllers/schedules.controller.ts +++ b/apps/api/v2/src/ee/schedules/schedules_2024_06_11/controllers/schedules.controller.ts @@ -57,17 +57,19 @@ export class SchedulesController_2024_06_11 { @ApiOperation({ summary: "Create a schedule", description: ` + Create a schedule for the authenticated user. + The point of creating schedules is for event types to be available at specific times. - First goal of schedules is to have a default schedule. If you are platform customer and created managed users, then it is important to note that each managed user should have a default schedule. - 1. If you passed \`timeZone\` when creating managed user, then the default schedule from Monday to Friday from 9AM to 5PM will be created with that timezone. Managed user can then change the default schedule via \`AvailabilitySettings\` atom. - 2. If you did not, then we assume you want that user has specific schedule right away. You should create default schedule by specifying - \`"isDefault": true\` in the request body. Until the user has a default schedule that user can't be booked or manage his / her schedule via the AvailabilitySettings atom. + The first goal of schedules is to have a default schedule. If you are platform customer and created managed users, then it is important to note that each managed user should have a default schedule. + 1. If you passed \`timeZone\` when creating managed user, then the default schedule from Monday to Friday from 9AM to 5PM will be created with that timezone. The managed user can then change the default schedule via the \`AvailabilitySettings\` atom. + 2. If you did not, then we assume you want the user to have this specific schedule right away. You should create a default schedule by specifying + \`"isDefault": true\` in the request body. Until the user has a default schedule the user can't be booked nor manage their schedule via the AvailabilitySettings atom. - Second goal is to create other schedules that event types can point to, so that when that event is booked availability is not checked against the default schedule but against that specific schedule. - After creating a non default schedule you can update event type to point to that schedule via the PATCH \`event-types/{eventTypeId}\` endpoint. + The second goal of schedules is to create another schedule that event types can point to. This is useful for when an event is booked because availability is not checked against the default schedule but instead against that specific schedule. + After creating a non-default schedule, you can update an event type to point to that schedule via the PATCH \`event-types/{eventTypeId}\` endpoint. - When specifying start time and end time for each day use 24 hour format e.g. 08:00, 15:00 etc. + When specifying start time and end time for each day use the 24 hour format e.g. 08:00, 15:00 etc. `, }) async createSchedule( @@ -86,10 +88,12 @@ export class SchedulesController_2024_06_11 { @Permissions([SCHEDULE_READ]) @ApiResponse({ status: 200, - description: "Returns the default schedule of the authenticated user", type: GetDefaultScheduleOutput_2024_06_11, }) - @ApiOperation({ summary: "Get default schedule (of the authenticated user)" }) + @ApiOperation({ + summary: "Get default schedule", + description: "Get the default schedule of the authenticated user.", + }) async getDefaultSchedule(@GetUser() user: UserWithProfile): Promise { const schedule = await this.schedulesService.getUserScheduleDefault(user.id); @@ -117,7 +121,10 @@ export class SchedulesController_2024_06_11 { @Get("/") @Permissions([SCHEDULE_READ]) - @ApiOperation({ summary: "Get all schedules (of the authenticated user)" }) + @ApiOperation({ + summary: "Get all schedules", + description: "Get all schedules of the authenticated user.", + }) async getSchedules(@GetUser() user: UserWithProfile): Promise { const schedules = await this.schedulesService.getUserSchedules(user.id);