From 279c3da21f32ef84566e06a09e4fe8bdb0d528dc Mon Sep 17 00:00:00 2001 From: Syed Ali Shahbaz <52925846+alishaz-polymath@users.noreply.github.com> Date: Tue, 7 Feb 2023 21:11:08 +0530 Subject: [PATCH] Improves Booking docs in swagger (#219) Adds definition to booking swagger definition, and fixes user _post definition example --- pages/api/bookings/[id]/_delete.ts | 37 +++++++++++-- pages/api/bookings/[id]/_get.ts | 6 +++ pages/api/bookings/[id]/_patch.ts | 45 ++++++++++++++-- pages/api/bookings/_get.ts | 21 ++++++++ pages/api/bookings/_post.ts | 87 ++++++++++++++++++++++++------ pages/api/users/_post.ts | 20 +++---- 6 files changed, 183 insertions(+), 33 deletions(-) diff --git a/pages/api/bookings/[id]/_delete.ts b/pages/api/bookings/[id]/_delete.ts index a48e53b9ae..c2bc3cf5d9 100644 --- a/pages/api/bookings/[id]/_delete.ts +++ b/pages/api/bookings/[id]/_delete.ts @@ -29,6 +29,19 @@ import { schemaQueryIdParseInt } from "~/lib/validations/shared/queryIdTransform * type: integer * required: true * description: ID of the booking to cancel + * parameters: + * - in: path + * name: id + * schema: + * type: integer + * required: true + * description: ID of the booking to get + * - in: query + * name: apiKey + * required: true + * schema: + * type: string + * description: Your API key * tags: * - bookings * responses: @@ -36,11 +49,25 @@ import { schemaQueryIdParseInt } from "~/lib/validations/shared/queryIdTransform * description: OK, booking cancelled successfuly * 400: * description: | - * Message | Cause - * :--|:-- - * Booking not found| The provided id didn't correspond to any existing booking. - * Cannot cancel past events| The provided id matched an existing booking with a past startDate. - * User not found| The userId did not matched an existing user. + * Bad request + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
MessageCause
Booking not foundThe provided id didn't correspond to any existing booking.
Cannot cancel past eventsThe provided id matched an existing booking with a past startDate.
User not foundThe userId did not matched an existing user.
* 404: * description: User not found */ diff --git a/pages/api/bookings/[id]/_get.ts b/pages/api/bookings/[id]/_get.ts index a15f993077..2d6ae07a64 100644 --- a/pages/api/bookings/[id]/_get.ts +++ b/pages/api/bookings/[id]/_get.ts @@ -18,6 +18,12 @@ import { schemaQueryIdParseInt } from "~/lib/validations/shared/queryIdTransform * type: integer * required: true * description: ID of the booking to get + * - in: query + * name: apiKey + * required: true + * schema: + * type: string + * description: Your API key * tags: * - bookings * responses: diff --git a/pages/api/bookings/[id]/_patch.ts b/pages/api/bookings/[id]/_patch.ts index fc20c14709..55b20bc9c1 100644 --- a/pages/api/bookings/[id]/_patch.ts +++ b/pages/api/bookings/[id]/_patch.ts @@ -23,14 +23,53 @@ import { schemaQueryIdParseInt } from "~/lib/validations/shared/queryIdTransform * properties: * title: * type: string - * example: 15min + * description: 'Booking event title' * startTime: * type: string - * example: 1970-01-01T17:00:00.000Z + * format: date-time + * description: 'Start time of the Event' * endTime: * type: string - * example: 1970-01-01T17:00:00.000Z + * format: date-time + * description: 'End time of the Event' + * recurringEventId: + * type: integer + * description: 'Recurring event ID if the event is recurring' + * description: + * type: string + * description: 'Event description' + * status: + * type: string + * description: 'Acceptable values one of ["ACCEPTED", "PENDING", "CANCELLED", "REJECTED"]' + * location: + * type: string + * description: 'Meeting location' + * smsReminderNumber: + * type: number + * description: 'SMS reminder number' + * attendees: + * type: array + * description: 'List of attendees of the booking' + * items: + * type: object + * properties: + * name: + * type: string + * email: + * type: string + * format: email + * timeZone: + * type: string + * locale: + * type: string + * * parameters: + * - in: query + * name: apiKey + * required: true + * schema: + * type: string + * description: Your API key * - in: path * name: id * schema: diff --git a/pages/api/bookings/_get.ts b/pages/api/bookings/_get.ts index cdb9f1627f..9476d07e09 100644 --- a/pages/api/bookings/_get.ts +++ b/pages/api/bookings/_get.ts @@ -12,7 +12,28 @@ import { schemaQuerySingleOrMultipleUserIds } from "~/lib/validations/shared/que * /bookings: * get: * summary: Find all bookings + * parameters: + * - in: query + * name: apiKey + * required: true + * schema: + * type: string + * description: Your API key * operationId: listBookings + * requestBody: + * description: Find all bookings + * content: + * application/json: + * schema: + * type: object + * properties: + * userId: + * description: 'The user(s) to get the booking for, if the request is by an Admin' + * oneOf: + * - type: integer + * - type: array + * items: + * type: integer * tags: * - bookings * responses: diff --git a/pages/api/bookings/_post.ts b/pages/api/bookings/_post.ts index af3099dd85..ff3ac36e02 100644 --- a/pages/api/bookings/_post.ts +++ b/pages/api/bookings/_post.ts @@ -8,42 +8,99 @@ import { defaultResponder } from "@calcom/lib/server"; * /bookings: * post: * summary: Creates a new booking + * parameters: + * - in: query + * name: apiKey + * required: true + * schema: + * type: string + * description: Your API key * operationId: addBooking * requestBody: - * description: Edit an existing booking related to one of your event-types + * description: Create a new booking related to one of your event-types * required: true * content: * application/json: * schema: * type: object + * required: + * - startTime + * - endTime * properties: * title: * type: string - * example: 15min + * description: 'Booking event title' * startTime: * type: string - * example: 1970-01-01T17:00:00.000Z + * format: date-time + * description: 'Start time of the Event' * endTime: * type: string - * example: 1970-01-01T17:00:00.000Z - * recurringCount: + * format: date-time + * description: 'End time of the Event' + * recurringEventId: + * type: integer + * description: 'Recurring event ID if the event is recurring' + * description: + * type: string + * description: 'Event description' + * status: + * type: string + * description: 'Acceptable values one of ["ACCEPTED", "PENDING", "CANCELLED", "REJECTED"]' + * location: + * type: string + * description: 'Meeting location' + * smsReminderNumber: * type: number - * example: 8 + * description: 'SMS reminder number' + * attendees: + * type: array + * description: 'List of attendees of the booking' + * items: + * type: object + * properties: + * name: + * type: string + * email: + * type: string + * format: email + * timeZone: + * type: string + * locale: + * type: string + * * tags: - * - bookings + * - bookings * responses: * 201: * description: Booking(s) created successfully. * 400: - * description: | - * Message | Cause - * :--|:-- - * Booking body is invalid| Missing property on booking entity. - * Invalid eventTypeId| The provided eventTypeId does not exist. - * Missing recurringCount| The eventType is recurring, and no recurringCount was passed. - * Invalid recurringCount| The provided recurringCount is greater than the eventType recurring config + * description: | + * Bad request + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
MessageCause
Booking body is invalidMissing property on booking entity.
Invalid eventTypeIdThe provided eventTypeId does not exist.
Missing recurringCountThe eventType is recurring, and no recurringCount was passed.
Invalid recurringCountThe provided recurringCount is greater than the eventType recurring config
* 401: - * description: Authorization information is missing or invalid. + * description: Authorization information is missing or invalid. */ async function handler(req: NextApiRequest) { const { userId, isAdmin } = req; diff --git a/pages/api/users/_post.ts b/pages/api/users/_post.ts index 2346e35876..3ee8c222d5 100644 --- a/pages/api/users/_post.ts +++ b/pages/api/users/_post.ts @@ -46,7 +46,7 @@ import { schemaUserCreateBodyParams } from "~/lib/validations/user"; * description: Start of the week. Acceptable values are one of [SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY] * type: string * timeZone: - * description: The new user's time zone + * description: The new user's time zone. Eg: 'EUROPE/PARIS' * type: string * theme: * description: Default theme for the new user. Acceptable values are one of [DARK, LIGHT] @@ -61,15 +61,15 @@ import { schemaUserCreateBodyParams } from "~/lib/validations/user"; * user: * summary: An example of USER * value: - * email: email@example.com - * username: johndoe - * weekStart: MONDAY - * brandColor: #555555 - * darkBrandColor: #111111 - * timeZone: EUROPE/PARIS - * theme: LIGHT - * timeFormat: TWELVE - * locale: FR + * email: 'email@example.com' + * username: 'johndoe' + * weekStart: 'MONDAY' + * brandColor: '#555555' + * darkBrandColor: '#111111' + * timeZone: 'EUROPE/PARIS' + * theme: 'LIGHT' + * timeFormat: 'TWELVE' + * locale: 'FR' * tags: * - users * responses: