docs: v2 schedules and event-types swagger (#16608)

* docs: schedules

* docs: wip event-types

* docs:event-types

* docs:event-types

* Delete yarn.lock

* Revert "Delete yarn.lock"

This reverts commit bb3eb23508c0fa2e216ba7bcb97756215f889daa.

---------

Co-authored-by: Morgan <33722304+ThyMinimalDev@users.noreply.github.com>

apps/api/v2/src/ee/event-types/event-types_2024_04_15/controllers/event-types.controller.ts

@@ -36,7 +36,7 @@ import {
   InternalServerErrorException,
   ParseIntPipe,
 } from "@nestjs/common";
-import { ApiTags as DocsTags } from "@nestjs/swagger";
+import { ApiExcludeController as DocsExcludeController } from "@nestjs/swagger";
 
 import { EVENT_TYPE_READ, EVENT_TYPE_WRITE, SUCCESS_STATUS } from "@calcom/platform-constants";
 import { getPublicEvent, getEventTypesByViewer } from "@calcom/platform-libraries-0.0.2";
@@ -47,7 +47,7 @@ import { PrismaClient } from "@calcom/prisma";
   version: [VERSION_2024_04_15, VERSION_2024_06_11],
 })
 @UseGuards(PermissionsGuard)
-@DocsTags("Event types")
+@DocsExcludeController(true)
 export class EventTypesController_2024_04_15 {
   constructor(
     private readonly eventTypesService: EventTypesService_2024_04_15,

apps/api/v2/src/ee/event-types/event-types_2024_06_14/controllers/event-types.controller.ts

@@ -24,7 +24,7 @@ import {
   Delete,
   Query,
 } from "@nestjs/common";
-import { ApiTags as DocsTags } from "@nestjs/swagger";
+import { ApiHeader, ApiTags as DocsTags } from "@nestjs/swagger";
 
 import { EVENT_TYPE_READ, EVENT_TYPE_WRITE, SUCCESS_STATUS } from "@calcom/platform-constants";
 import {
@@ -39,12 +39,23 @@ import {
 })
 @UseGuards(PermissionsGuard)
 @DocsTags("Event types")
+@ApiHeader({
+  name: "cal-api-version",
+  description: `Must be set to \`2024-06-14\``,
+  required: true,
+})
 export class EventTypesController_2024_06_14 {
   constructor(private readonly eventTypesService: EventTypesService_2024_06_14) {}
 
   @Post("/")
   @Permissions([EVENT_TYPE_WRITE])
   @UseGuards(ApiAuthGuard)
+  @ApiHeader({
+    name: "Authorization",
+    description:
+      "value must be `Bearer <token>` where `<token>` either managed user access token or api key prefixed with cal_",
+    required: true,
+  })
   async createEventType(
     @Body() body: CreateEventTypeInput_2024_06_14,
     @GetUser() user: UserWithProfile
@@ -60,6 +71,12 @@ export class EventTypesController_2024_06_14 {
   @Get("/:eventTypeId")
   @Permissions([EVENT_TYPE_READ])
   @UseGuards(ApiAuthGuard)
+  @ApiHeader({
+    name: "Authorization",
+    description:
+      "value must be `Bearer <token>` where `<token>` either managed user access token or api key prefixed with cal_",
+    required: true,
+  })
   async getEventTypeById(
     @Param("eventTypeId") eventTypeId: string,
     @GetUser() user: UserWithProfile
@@ -91,6 +108,12 @@ export class EventTypesController_2024_06_14 {
   @Patch("/:eventTypeId")
   @Permissions([EVENT_TYPE_WRITE])
   @UseGuards(ApiAuthGuard)
+  @ApiHeader({
+    name: "Authorization",
+    description:
+      "value must be `Bearer <token>` where `<token>` either managed user access token or api key prefixed with cal_",
+    required: true,
+  })
   @HttpCode(HttpStatus.OK)
   async updateEventType(
     @Param("eventTypeId") eventTypeId: number,
@@ -108,6 +131,12 @@ export class EventTypesController_2024_06_14 {
   @Delete("/:eventTypeId")
   @Permissions([EVENT_TYPE_WRITE])
   @UseGuards(ApiAuthGuard)
+  @ApiHeader({
+    name: "Authorization",
+    description:
+      "value must be `Bearer <token>` where `<token>` either managed user access token or api key prefixed with cal_",
+    required: true,
+  })
   async deleteEventType(
     @Param("eventTypeId") eventTypeId: number,
     @GetUser("id") userId: number

apps/api/v2/src/ee/schedules/schedules_2024_04_15/controllers/schedules.controller.ts

@@ -23,7 +23,7 @@ import {
   Patch,
   UseGuards,
 } from "@nestjs/common";
-import { ApiResponse, ApiTags as DocsTags } from "@nestjs/swagger";
+import { ApiResponse, ApiExcludeController as DocsExcludeController } from "@nestjs/swagger";
 import { Throttle } from "@nestjs/throttler";
 
 import { SCHEDULE_READ, SCHEDULE_WRITE, SUCCESS_STATUS } from "@calcom/platform-constants";
@@ -36,7 +36,7 @@ import { CreateScheduleInput_2024_04_15 } from "../inputs/create-schedule.input"
   version: VERSION_2024_04_15_VALUE,
 })
 @UseGuards(ApiAuthGuard, PermissionsGuard)
-@DocsTags("Schedules")
+@DocsExcludeController(true)
 export class SchedulesController_2024_04_15 {
   constructor(private readonly schedulesService: SchedulesService_2024_04_15) {}
 

apps/api/v2/src/ee/schedules/schedules_2024_06_11/controllers/schedules.controller.ts

@@ -17,7 +17,7 @@ import {
   Patch,
   UseGuards,
 } from "@nestjs/common";
-import { ApiResponse, ApiTags as DocsTags } from "@nestjs/swagger";
+import { ApiHeader, ApiOperation, ApiResponse, ApiTags as DocsTags } from "@nestjs/swagger";
 import { Throttle } from "@nestjs/throttler";
 
 import { SCHEDULE_READ, SCHEDULE_WRITE, SUCCESS_STATUS } from "@calcom/platform-constants";
@@ -38,11 +38,38 @@ import {
 })
 @UseGuards(ApiAuthGuard, PermissionsGuard)
 @DocsTags("Schedules")
+@ApiHeader({
+  name: "cal-api-version",
+  description: `Must be set to \`2024-06-11\``,
+  required: true,
+})
+@ApiHeader({
+  name: "Authorization",
+  description:
+    "value must be `Bearer <token>` where `<token>` either managed user access token or api key prefixed with cal_",
+  required: true,
+})
 export class SchedulesController_2024_06_11 {
   constructor(private readonly schedulesService: SchedulesService_2024_06_11) {}
 
   @Post("/")
   @Permissions([SCHEDULE_WRITE])
+  @ApiOperation({
+    summary: "Create a schedule",
+    description: `
+      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.
+
+      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.
+
+      When specifying start time and end time for each day use 24 hour format e.g. 08:00, 15:00 etc.
+      `,
+  })
   async createSchedule(
     @GetUser() user: UserWithProfile,
     @Body() bodySchedule: CreateScheduleInput_2024_06_11
@@ -59,7 +86,7 @@ export class SchedulesController_2024_06_11 {
   @Permissions([SCHEDULE_READ])
   @ApiResponse({
     status: 200,
-    description: "Returns the default schedule",
+    description: "Returns the default schedule of the authenticated user",
     type: GetDefaultScheduleOutput_2024_06_11,
   })
   async getDefaultSchedule(@GetUser() user: UserWithProfile): Promise<GetScheduleOutput_2024_06_11> {
@@ -88,6 +115,9 @@ export class SchedulesController_2024_06_11 {
 
   @Get("/")
   @Permissions([SCHEDULE_READ])
+  @ApiOperation({
+    description: "Returns all schedules of the authenticated user",
+  })
   async getSchedules(@GetUser() user: UserWithProfile): Promise<GetSchedulesOutput_2024_06_11> {
     const schedules = await this.schedulesService.getUserSchedules(user.id);
 

apps/api/v2/src/modules/oauth-clients/controllers/oauth-client-users/oauth-client-users.controller.ts

@@ -79,7 +79,6 @@ export class OAuthClientUsersController {
       `Creating user with data: ${JSON.stringify(body, null, 2)} for OAuth Client with ID ${oAuthClientId}`
     );
     const client = await this.oauthRepository.getOAuthClient(oAuthClientId);
-    console.log("asap createUser client", JSON.stringify(client, null, 2));
 
     const isPlatformManaged = true;
     const { user, tokens } = await this.oAuthClientUsersService.createOauthClientUser(

apps/api/v2/src/modules/users/inputs/create-managed-user.input.ts

@@ -29,7 +29,11 @@ export class CreateManagedUserInput {
   @IsTimeZone()
   @IsOptional()
   @CapitalizeTimeZone()
-  @ApiProperty({ example: "America/New_York" })
+  @ApiProperty({
+    example: "America/New_York",
+    description: `Timezone is used to create user's default schedule from Monday to Friday from 9AM to 5PM. If it is not passed then user does not have
+      a default schedule and it must be created manually via the /schedules endpoint. Until the schedule is created, the user can't access availability atom to set his / her availability nor booked.`,
+  })
   timeZone?: string;
 
   @IsEnum(Locales)