docs: v2 refresh tokens and slots endpoints swagger (#16788)

* docs: oauth refresh endpoint

* docs: slots reserve and delete

* docs: get slots

* swagger

* fix: reserving slot

* Revert "fix: reserving slot"

This reverts commit 8a3ce8464d5dbf67e58da6d3b1aeb51df97240cb.

* Update oauth-flow.controller.ts

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

@@ -25,9 +25,11 @@ import {
 import {
   ApiTags as DocsTags,
   ApiExcludeController as DocsExcludeController,
+  ApiExcludeEndpoint as DocsExcludeEndpoint,
   ApiOperation as DocsOperation,
   ApiOkResponse as DocsOkResponse,
   ApiBadRequestResponse as DocsBadRequestResponse,
+  ApiHeader as DocsHeader,
 } from "@nestjs/swagger";
 import { Response as ExpressResponse } from "express";
 
@@ -37,8 +39,7 @@ import { SUCCESS_STATUS, X_CAL_SECRET_KEY } from "@calcom/platform-constants";
   path: "/v2/oauth/:clientId",
   version: API_VERSIONS_VALUES,
 })
-@DocsExcludeController(getEnv("NODE_ENV") === "production")
-@DocsTags("OAuth - development only")
+@DocsTags("OAuth")
 export class OAuthFlowController {
   constructor(
     private readonly oauthClientRepository: OAuthClientRepository,
@@ -62,6 +63,7 @@ export class OAuthFlowController {
     description:
       "Bad request if the OAuth client is not found, if the redirect URI is invalid, or if the user has already authorized the client.",
   })
+  @DocsExcludeEndpoint(getEnv("NODE_ENV") === "production")
   async authorize(
     @Param("clientId") clientId: string,
     @Body() body: OAuthAuthorizeInput,
@@ -108,6 +110,7 @@ export class OAuthFlowController {
     description:
       "Bad request if the authorization code is missing, invalid, or if the client ID and secret do not match.",
   })
+  @DocsExcludeEndpoint(getEnv("NODE_ENV") === "production")
   async exchange(
     @Headers("Authorization") authorization: string,
     @Param("clientId") clientId: string,
@@ -138,6 +141,12 @@ export class OAuthFlowController {
   @Post("/refresh")
   @HttpCode(HttpStatus.OK)
   @UseGuards(ApiAuthGuard)
+  @DocsTags("Managed users")
+  @DocsHeader({
+    name: X_CAL_SECRET_KEY,
+    description: "OAuth client secret key.",
+    required: true,
+  })
   async refreshAccessToken(
     @Param("clientId") clientId: string,
     @Headers(X_CAL_SECRET_KEY) secretKey: string,

apps/api/v2/src/modules/oauth-clients/inputs/refresh-token.input.ts

@@ -1,6 +1,8 @@
+import { ApiProperty as DocsProperty } from "@nestjs/swagger";
 import { IsString } from "class-validator";
 
 export class RefreshTokenInput {
   @IsString()
+  @DocsProperty({ description: "Managed user's refresh token." })
   refreshToken!: string;
 }

apps/api/v2/src/modules/slots/controllers/slots.controller.ts

@@ -1,7 +1,7 @@
 import { API_VERSIONS_VALUES } from "@/lib/api-versions";
 import { SlotsService } from "@/modules/slots/services/slots.service";
 import { Query, Body, Controller, Get, Delete, Post, Req, Res } from "@nestjs/common";
-import { ApiOperation, ApiTags as DocsTags } from "@nestjs/swagger";
+import { ApiTags as DocsTags, ApiCreatedResponse, ApiOkResponse, ApiOperation } from "@nestjs/swagger";
 import { Response as ExpressResponse, Request as ExpressRequest } from "express";
 
 import { SUCCESS_STATUS } from "@calcom/platform-constants";
@@ -19,6 +19,21 @@ export class SlotsController {
   constructor(private readonly slotsService: SlotsService) {}
 
   @Post("/reserve")
+  @ApiCreatedResponse({
+    description: "Successful response returning uid of reserved slot.",
+    schema: {
+      type: "object",
+      properties: {
+        status: { type: "string", example: "success" },
+        data: {
+          type: "object",
+          properties: {
+            uid: { type: "string", example: "e2a7bcf9-cc7b-40a0-80d3-657d391775a6" },
+          },
+        },
+      },
+    },
+  })
   @ApiOperation({ summary: "Reserve a slot" })
   async reserveSlot(
     @Body() body: ReserveSlotInput,
@@ -35,6 +50,15 @@ export class SlotsController {
   }
 
   @Delete("/selected-slot")
+  @ApiOkResponse({
+    description: "Response deleting reserved slot by uid.",
+    schema: {
+      type: "object",
+      properties: {
+        status: { type: "string", example: "success" },
+      },
+    },
+  })
   @ApiOperation({ summary: "Delete a selected slot" })
   async deleteSelectedSlot(
     @Query() params: RemoveSelectedSlotInput,
@@ -50,6 +74,45 @@ export class SlotsController {
   }
 
   @Get("/available")
+  @ApiOkResponse({
+    description: "Available time slots retrieved successfully",
+    schema: {
+      type: "object",
+      properties: {
+        status: { type: "string", example: "success" },
+        data: {
+          type: "object",
+          properties: {
+            slots: {
+              type: "object",
+              additionalProperties: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    time: { type: "string", format: "date-time", example: "2024-09-25T08:00:00.000Z" },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      example: {
+        status: "success",
+        data: {
+          slots: {
+            "2024-09-25": [{ time: "2024-09-25T08:00:00.000Z" }, { time: "2024-09-25T08:15:00.000Z" }],
+            "2024-09-26": [
+              { time: "2024-09-26T08:00:00.000Z" },
+              { time: "2024-09-26T08:15:00.000Z" },
+              { time: "2024-09-26T08:30:00.000Z" },
+            ],
+          },
+        },
+      },
+    },
+  })
   @ApiOperation({ summary: "Get available slots" })
   async getAvailableSlots(
     @Query() query: GetAvailableSlotsInput,