Updates Availability and Attendees swagger docs, hotfixes Booking API doc (#241)

- Adds swagger definition and swagger fixes to /availability and
/attendees
- Also fixes Booking API endpoint definition (startTime -> start,
endTime -> end)

pages/api/attendees/[id]/_delete.ts

@@ -11,6 +11,12 @@ import { schemaQueryIdParseInt } from "~/lib/validations/shared/queryIdTransform
  *     operationId: removeAttendeeById
  *     summary: Remove an existing attendee
  *     parameters:
+ *      - in: query
+ *        name: apiKey
+ *        required: true
+ *        schema:
+ *          type: string
+ *        description: Your API key
  *      - in: path
  *        name: id
  *        schema:
@@ -21,7 +27,7 @@ import { schemaQueryIdParseInt } from "~/lib/validations/shared/queryIdTransform
  *     - attendees
  *     responses:
  *       201:
- *         description: OK, attendee removed successfuly
+ *         description: OK, attendee removed successfully
  *       400:
  *        description: Bad request. Attendee id is invalid.
  *       401:

pages/api/attendees/[id]/_get.ts

@@ -12,13 +12,18 @@ import { schemaQueryIdParseInt } from "~/lib/validations/shared/queryIdTransform
  *     operationId: getAttendeeById
  *     summary: Find an attendee
  *     parameters:
+ *       - in: query
+ *         name: apiKey
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Your API key
  *       - in: path
  *         name: id
  *         schema:
  *           type: integer
  *         required: true
  *         description: ID of the attendee to get
- *         example: 3
  *     tags:
  *     - attendees
  *     responses:

pages/api/attendees/[id]/_patch.ts

@@ -11,8 +11,8 @@ import { schemaQueryIdParseInt } from "~/lib/validations/shared/queryIdTransform
  * @swagger
  * /attendees/{id}:
  *   patch:
- *     summary: Edit an existing attendee
  *     operationId: editAttendeeById
+ *     summary: Edit an existing attendee
  *     requestBody:
  *       description: Edit an existing attendee related to one of your bookings
  *       required: true
@@ -23,31 +23,35 @@ import { schemaQueryIdParseInt } from "~/lib/validations/shared/queryIdTransform
  *             properties:
  *               email:
  *                 type: string
- *                 example: email@example.com
+ *                 format: email
  *               name:
  *                 type: string
- *                 example: John Doe
  *               timeZone:
  *                 type: string
- *                 example: Europe/London
  *     parameters:
- *      - in: path
+ *       - in: query
- *        name: id
+ *         name: apiKey
- *        schema:
+ *         required: true
- *          type: integer
+ *         schema:
- *          example: 3
+ *           type: string
- *        required: true
+ *         description: Your API key
- *        description: ID of the attendee to edit
+ *       - in: path
+ *         name: id
+ *         schema:
+ *           type: integer
+ *         required: true
+ *         description: ID of the attendee to get
  *     tags:
  *     - attendees
  *     responses:
  *       201:
- *         description: OK, attendee edited successfuly
+ *         description: OK, attendee edited successfully
  *       400:
  *        description: Bad request. Attendee body is invalid.
  *       401:
  *        description: Authorization information is missing or invalid.
  */
+
 export async function patchHandler(req: NextApiRequest) {
   const { prisma, query, body } = req;
   const { id } = schemaQueryIdParseInt.parse(query);

pages/api/attendees/_get.ts

@@ -12,6 +12,13 @@ import { schemaAttendeeReadPublic } from "~/lib/validations/attendee";
  *   get:
  *     operationId: listAttendees
  *     summary: Find all attendees
+ *     parameters:
+ *       - in: query
+ *         name: apiKey
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Your API key
  *     tags:
  *     - attendees
  *     responses:

pages/api/attendees/_post.ts

@@ -11,6 +11,13 @@ import { schemaAttendeeCreateBodyParams, schemaAttendeeReadPublic } from "~/lib/
  *   post:
  *     operationId: addAttendee
  *     summary: Creates a new attendee
+ *     parameters:
+ *       - in: query
+ *         name: apiKey
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Your API key
  *     requestBody:
  *       description: Create a new attendee related to one of your bookings
  *       required: true
@@ -26,16 +33,13 @@ import { schemaAttendeeCreateBodyParams, schemaAttendeeReadPublic } from "~/lib/
  *             properties:
  *               bookingId:
  *                 type: number
- *                 example: 1
  *               email:
  *                 type: string
- *                 example: email@example.com
+ *                 format: email
  *               name:
  *                 type: string
- *                 example: John Doe
  *               timeZone:
  *                 type: string
- *                 example: Europe/London
  *     tags:
  *     - attendees
  *     responses:

pages/api/availability/_get.ts

@@ -7,6 +7,62 @@ import { defaultResponder } from "@calcom/lib/server";
 import { availabilityUserSelect } from "@calcom/prisma";
 import { stringOrNumber } from "@calcom/prisma/zod-utils";
 
+/**
+ * @swagger
+ * /availability:
+ *   get:
+ *     summary: Find user or team availability
+ *     parameters:
+ *       - in: query
+ *         name: apiKey
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Your API key
+ *       - in: query
+ *         name: userId
+ *         schema:
+ *           type: integer
+ *         description: ID of the user to fetch the availability for
+ *       - in: query
+ *         name: teamId
+ *         schema:
+ *           type: integer
+ *         description: ID of the team to fetch the availability for
+ *       - in: query
+ *         name: username
+ *         schema:
+ *           type: string
+ *         description: username of the user to fetch the availability for
+ *       - in: query
+ *         name: dateFrom
+ *         schema:
+ *           type: string
+ *           format: date
+ *         description: Start Date of the availability query
+ *       - in: query
+ *         name: dateTo
+ *         schema:
+ *           type: string
+ *           format: date
+ *         description: End Date of the availability query
+ *       - in: query
+ *         name: eventTypeId
+ *         schema:
+ *           type: integer
+ *         description: Event Type ID of the event type to fetch the availability for
+ *     operationId: availability
+ *     tags:
+ *     - availability
+ *     responses:
+ *       200:
+ *         description: OK
+ *       401:
+ *        description: Authorization information is missing or invalid.
+ *       404:
+ *         description: User not found | Team not found | Team has no members
+ */
+
 const availabilitySchema = z
   .object({
     userId: stringOrNumber.optional(),

pages/api/bookings/[id]/_patch.ts

@@ -24,11 +24,11 @@ import { schemaQueryIdParseInt } from "~/lib/validations/shared/queryIdTransform
  *               title:
  *                 type: string
  *                 description: 'Booking event title'
- *               startTime:
+ *               start:
  *                 type: string
  *                 format: date-time
  *                 description: 'Start time of the Event'
- *               endTime:
+ *               end:
  *                 type: string
  *                 format: date-time
  *                 description: 'End time of the Event'

pages/api/bookings/_post.ts

@@ -24,17 +24,17 @@ import { defaultResponder } from "@calcom/lib/server";
  *           schema:
  *             type: object
  *             required:
- *               - startTime
+ *               - start
- *               - endTime
+ *               - end
  *             properties:
  *               title:
  *                 type: string
  *                 description: 'Booking event title'
- *               startTime:
+ *               start:
  *                 type: string
  *                 format: date-time
  *                 description: 'Start time of the Event'
- *               endTime:
+ *               end:
  *                 type: string
  *                 format: date-time
  *                 description: 'End time of the Event'