chore: update docs to make sure to inform users to pass in cal-api-version header (calcom#24364)

Author: Ryukemeister

apps/api/v2/src/ee/bookings/2024-08-13/controllers/bookings.controller.ts

@@ -87,7 +87,7 @@ import {
 @DocsTags("Bookings")
 @ApiHeader({
   name: "cal-api-version",
-  description: `Must be set to ${VERSION_2024_08_13}`,
+  description: `Must be set to ${VERSION_2024_08_13}. If not set to this value, the endpoint will default to an older version.`,
   example: VERSION_2024_08_13,
   required: true,
   schema: {
@@ -133,6 +133,8 @@ export class BookingsController_2024_08_13 {
 
       If you are creating a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or
       you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.
+
+      <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
       `,
   })
   @ApiBody({
@@ -188,6 +190,8 @@ export class BookingsController_2024_08_13 {
       
       If you are fetching a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or
       you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.
+
+      <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
       `,
   })
   async getBooking(
@@ -206,7 +210,10 @@ export class BookingsController_2024_08_13 {
   @UseGuards(BookingUidGuard)
   @ApiOperation({
     summary: "Get all the recordings for the booking",
-    description: `Fetches all the recordings for the booking \`:bookingUid\``,
+    description: `Fetches all the recordings for the booking \`:bookingUid\`
+    
+    <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
+    `,
   })
   async getBookingRecordings(@Param("bookingUid") bookingUid: string): Promise<GetBookingRecordingsOutput> {
     const recordings = await this.calVideoService.getRecordings(bookingUid);
@@ -221,7 +228,10 @@ export class BookingsController_2024_08_13 {
   @UseGuards(BookingUidGuard)
   @ApiOperation({
     summary: "Get all the transcripts download links for the booking",
-    description: `Fetches all the transcripts download links for the booking \`:bookingUid\``,
+    description: `Fetches all the transcripts download links for the booking \`:bookingUid\`
+    
+    <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
+    `,
   })
   async getBookingTranscripts(@Param("bookingUid") bookingUid: string): Promise<GetBookingTranscriptsOutput> {
     const transcripts = await this.calVideoService.getTranscripts(bookingUid);
@@ -236,7 +246,10 @@ export class BookingsController_2024_08_13 {
   @UseGuards(ApiAuthGuard)
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
   @Permissions([BOOKING_READ])
-  @ApiOperation({ summary: "Get all bookings" })
+  @ApiOperation({
+    summary: "Get all bookings",
+    description: `<Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>`,
+  })
   async getBookings(
     @Query() queryParams: GetBookingsInput_2024_08_13,
     @GetUser() user: ApiAuthGuardUser
@@ -263,7 +276,10 @@ export class BookingsController_2024_08_13 {
   @ApiHeader(OPTIONAL_API_KEY_OR_ACCESS_TOKEN_HEADER)
   @ApiOperation({
     summary: "Reschedule a booking",
-    description: "Reschedule a booking or seated booking",
+    description: `Reschedule a booking or seated booking
+    
+    <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
+    `,
   })
   @ApiBody({
     schema: {
@@ -315,6 +331,8 @@ export class BookingsController_2024_08_13 {
     
     If you are cancelling a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or
     you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.
+
+    <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
     `,
   })
   @ApiBody({
@@ -350,7 +368,10 @@ export class BookingsController_2024_08_13 {
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
   @ApiOperation({
     summary: "Mark a booking absence",
-    description: "The provided authorization header refers to the owner of the booking.",
+    description: `The provided authorization header refers to the owner of the booking.
+    
+    <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
+    `,
   })
   async markNoShow(
     @Param("bookingUid") bookingUid: string,
@@ -372,8 +393,10 @@ export class BookingsController_2024_08_13 {
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
   @ApiOperation({
     summary: "Reassign a booking to auto-selected host",
-    description:
-      "Currently only supports reassigning host for round robin bookings. The provided authorization header refers to the owner of the booking.",
+    description: `Currently only supports reassigning host for round robin bookings. The provided authorization header refers to the owner of the booking.
+      
+       <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
+      `,
   })
   async reassignBooking(
     @Param("bookingUid") bookingUid: string,
@@ -394,8 +417,10 @@ export class BookingsController_2024_08_13 {
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
   @ApiOperation({
     summary: "Reassign a booking to a specific host",
-    description:
-      "Currently only supports reassigning host for round robin bookings. The provided authorization header refers to the owner of the booking.",
+    description: `Currently only supports reassigning host for round robin bookings. The provided authorization header refers to the owner of the booking.
+      
+      <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
+      `,
   })
   async reassignBookingToUser(
     @Param("bookingUid") bookingUid: string,
@@ -423,7 +448,10 @@ export class BookingsController_2024_08_13 {
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
   @ApiOperation({
     summary: "Confirm a booking",
-    description: "The provided authorization header refers to the owner of the booking.",
+    description: `The provided authorization header refers to the owner of the booking.
+    
+    <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
+    `,
   })
   async confirmBooking(
     @Param("bookingUid") bookingUid: string,
@@ -444,7 +472,10 @@ export class BookingsController_2024_08_13 {
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
   @ApiOperation({
     summary: "Decline a booking",
-    description: "The provided authorization header refers to the owner of the booking.",
+    description: `The provided authorization header refers to the owner of the booking.
+    
+    <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note> 
+    `,
   })
   async declineBooking(
     @Param("bookingUid") bookingUid: string,
@@ -465,8 +496,10 @@ export class BookingsController_2024_08_13 {
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
   @ApiOperation({
     summary: "Get 'Add to Calendar' links for a booking",
-    description:
-      "Retrieve calendar links for a booking that can be used to add the event to various calendar services. Returns links for Google Calendar, Microsoft Office, Microsoft Outlook, and a downloadable ICS file.",
+    description: `Retrieve calendar links for a booking that can be used to add the event to various calendar services. Returns links for Google Calendar, Microsoft Office, Microsoft Outlook, and a downloadable ICS file.
+      
+      <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note> 
+      `,
   })
   @HttpCode(HttpStatus.OK)
   async getCalendarLinks(@Param("bookingUid") bookingUid: string): Promise<CalendarLinksOutput_2024_08_13> {
@@ -485,6 +518,7 @@ export class BookingsController_2024_08_13 {
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
   @ApiOperation({
     summary: "Get booking references",
+    description: `<Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>`,
   })
   @HttpCode(HttpStatus.OK)
   async getBookingReferences(

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

@@ -61,7 +61,7 @@ import {
 @DocsTags("Event Types")
 @ApiHeader({
   name: "cal-api-version",
-  description: `Must be set to ${VERSION_2024_06_14}`,
+  description: `Must be set to ${VERSION_2024_06_14}. If not set to this value, the endpoint will default to an older version.`,
   example: VERSION_2024_06_14,
   required: true,
   schema: {
@@ -80,7 +80,10 @@ export class EventTypesController_2024_06_14 {
   @Permissions([EVENT_TYPE_WRITE])
   @UseGuards(ApiAuthGuard)
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
-  @ApiOperation({ summary: "Create an event type" })
+  @ApiOperation({
+    summary: "Create an event type",
+    description: `<Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>`,
+  })
   async createEventType(
     @Body() body: CreateEventTypeInput_2024_06_14,
     @GetUser() user: UserWithProfile
@@ -102,7 +105,10 @@ export class EventTypesController_2024_06_14 {
   @Permissions([EVENT_TYPE_READ])
   @UseGuards(ApiAuthGuard)
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
-  @ApiOperation({ summary: "Get an event type" })
+  @ApiOperation({
+    summary: "Get an event type",
+    description: `<Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>`,
+  })
   async getEventTypeById(
     @Param("eventTypeId") eventTypeId: string,
     @GetUser() user: UserWithProfile
@@ -122,8 +128,10 @@ export class EventTypesController_2024_06_14 {
   @Get("/")
   @ApiOperation({
     summary: "Get all event types",
-    description:
-      "Hidden event types are returned only if authentication is provided and it belongs to the event type owner.",
+    description: `Hidden event types are returned only if authentication is provided and it belongs to the event type owner.
+      
+      <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
+      `,
   })
   @UseGuards(OptionalApiAuthGuard)
   @ApiHeader(OPTIONAL_X_CAL_CLIENT_ID_HEADER)
@@ -149,7 +157,10 @@ export class EventTypesController_2024_06_14 {
   @UseGuards(ApiAuthGuard)
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
   @HttpCode(HttpStatus.OK)
-  @ApiOperation({ summary: "Update an event type" })
+  @ApiOperation({
+    summary: "Update an event type",
+    description: `<Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>`,
+  })
   async updateEventType(
     @Param("eventTypeId", ParseIntPipe) eventTypeId: number,
     @Body() body: UpdateEventTypeInput_2024_06_14,
@@ -173,7 +184,10 @@ export class EventTypesController_2024_06_14 {
   @Permissions([EVENT_TYPE_WRITE])
   @UseGuards(ApiAuthGuard)
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
-  @ApiOperation({ summary: "Delete an event type" })
+  @ApiOperation({
+    summary: "Delete an event type",
+    description: `<Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>`,
+  })
   async deleteEventType(
     @Param("eventTypeId") eventTypeId: number,
     @GetUser("id") userId: number

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

@@ -40,7 +40,7 @@ import {
 @DocsTags("Schedules")
 @ApiHeader({
   name: "cal-api-version",
-  description: `Must be set to ${VERSION_2024_06_11}`,
+  description: `Must be set to ${VERSION_2024_06_11}. If not set to this value, the endpoint will default to an older version.`,
   example: VERSION_2024_06_11,
   required: true,
   schema: {
@@ -69,6 +69,8 @@ export class SchedulesController_2024_06_11 {
       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 the 24 hour format e.g. 08:00, 15:00 etc.
+
+      <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
       `,
   })
   async createSchedule(
@@ -91,7 +93,10 @@ export class SchedulesController_2024_06_11 {
   })
   @ApiOperation({
     summary: "Get default schedule",
-    description: "Get the default schedule of the authenticated user.",
+    description: `Get the default schedule of the authenticated user.
+    
+    <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
+    `,
   })
   async getDefaultSchedule(@GetUser() user: UserWithProfile): Promise<GetScheduleOutput_2024_06_11> {
     const schedule = await this.schedulesService.getUserScheduleDefault(user.id);
@@ -104,7 +109,10 @@ export class SchedulesController_2024_06_11 {
 
   @Get("/:scheduleId")
   @Permissions([SCHEDULE_READ])
-  @ApiOperation({ summary: "Get a schedule" })
+  @ApiOperation({
+    summary: "Get a schedule",
+    description: `<Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>`,
+  })
   async getSchedule(
     @GetUser() user: UserWithProfile,
     @Param("scheduleId") scheduleId: number
@@ -121,7 +129,10 @@ export class SchedulesController_2024_06_11 {
   @Permissions([SCHEDULE_READ])
   @ApiOperation({
     summary: "Get all schedules",
-    description: "Get all schedules of the authenticated user.",
+    description: `Get all schedules of the authenticated user.
+    
+     <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
+    `,
   })
   async getSchedules(@GetUser() user: UserWithProfile): Promise<GetSchedulesOutput_2024_06_11> {
     const schedules = await this.schedulesService.getUserSchedules(user.id);
@@ -134,7 +145,10 @@ export class SchedulesController_2024_06_11 {
 
   @Patch("/:scheduleId")
   @Permissions([SCHEDULE_WRITE])
-  @ApiOperation({ summary: "Update a schedule" })
+  @ApiOperation({
+    summary: "Update a schedule",
+    description: `<Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>`,
+  })
   async updateSchedule(
     @GetUser() user: UserWithProfile,
     @Body() bodySchedule: UpdateScheduleInput_2024_06_11,
@@ -155,7 +169,10 @@ export class SchedulesController_2024_06_11 {
   @Delete("/:scheduleId")
   @HttpCode(HttpStatus.OK)
   @Permissions([SCHEDULE_WRITE])
-  @ApiOperation({ summary: "Delete a schedule" })
+  @ApiOperation({
+    summary: "Delete a schedule",
+    description: `<Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>`,
+  })
   async deleteSchedule(
     @GetUser("id") userId: number,
     @Param("scheduleId") scheduleId: number