Swagger docs for webhooks (#245)

This PR updates and adds to the swagger documentation for /webhooks
endpoint

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

@@ -17,12 +17,16 @@ import { schemaQueryIdAsString } from "~/lib/validations/shared/queryIdString";
  *          type: integer
  *        required: true
  *        description: Numeric ID of the hooks to delete
- *     security:
- *       - ApiKeyAuth: []
+ *      - in: query
+ *        name: apiKey
+ *        required: true
+ *        schema:
+ *          type: string
+ *        description: Your API key
  *     tags:
- *     - hooks
+ *     - webhooks
  *     externalDocs:
- *        url: https://docs.cal.com/hooks
+ *        url: https://docs.cal.com/core-features/webhooks
  *     responses:
  *       201:
  *         description: OK, hook removed successfully

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

@@ -18,12 +18,16 @@ import { schemaWebhookReadPublic } from "~/lib/validations/webhook";
  *           type: integer
  *         required: true
  *         description: Numeric ID of the webhook to get
- *     security:
- *       - ApiKeyAuth: []
+ *       - in: query
+ *         name: apiKey
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Your API key
  *     tags:
- *     - hooks
+ *     - webhooks
  *     externalDocs:
- *        url: https://docs.cal.com/hooks
+ *        url: https://docs.cal.com/core-features/webhooks
  *     responses:
  *       200:
  *         description: OK

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

@@ -20,12 +20,41 @@ import { schemaWebhookEditBodyParams, schemaWebhookReadPublic } from "~/lib/vali
  *          type: integer
  *        required: true
  *        description: Numeric ID of the webhook to edit
- *     security:
- *       - ApiKeyAuth: []
+ *      - in: query
+ *        name: apiKey
+ *        required: true
+ *        schema:
+ *          type: string
+ *        description: Your API key
+ *     requestBody:
+ *       description: Edit an existing webhook
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               subscriberUrl:
+ *                 type: string
+ *                 format: uri
+ *                 description: The URL to subscribe to this webhook
+ *               eventTriggers:
+ *                 type: string
+ *                 enum: [BOOKING_CREATED, BOOKING_RESCHEDULED, BOOKING_CANCELLED, MEETING_ENDED]
+ *                 description: The events which should trigger this webhook call
+ *               active:
+ *                 type: boolean
+ *                 description: Whether the webhook is active and should trigger on associated trigger events
+ *               payloadTemplate:
+ *                 type: string
+ *                 description: The template of the webhook's payload
+ *               eventTypeId:
+ *                 type: number
+ *                 description: The event type ID if this webhook should be associated with only that event type
  *     tags:
- *     - hooks
+ *     - webhooks
  *     externalDocs:
- *        url: https://docs.cal.com/hooks
+ *        url: https://docs.cal.com/core-features/webhooks
  *     responses:
  *       201:
  *         description: OK, webhook edited successfully

pages/api/webhooks/_get.ts

@@ -13,10 +13,17 @@ import { schemaWebhookReadPublic } from "~/lib/validations/webhook";
  *   get:
  *     summary: Find all webhooks
  *     operationId: listWebhooks
+ *     parameters:
+ *       - in: query
+ *         name: apiKey
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Your API key
  *     tags:
- *     - hooks
+ *     - webhooks
  *     externalDocs:
- *        url: https://docs.cal.com/webhooks
+ *        url: https://docs.cal.com/core-features/webhooks
  *     responses:
  *       200:
  *         description: OK

pages/api/webhooks/_post.ts

@@ -9,14 +9,50 @@ import { schemaWebhookCreateBodyParams, schemaWebhookReadPublic } from "~/lib/va
 
 /**
  * @swagger
- * /hooks:
+ * /webhooks:
  *   post:
  *     summary: Creates a new webhook
  *     operationId: addWebhook
+ *     parameters:
+ *       - in: query
+ *         name: apiKey
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Your API key
+ *     requestBody:
+ *       description: Create a new webhook
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - subscriberUrl
+ *               - eventTriggers
+ *               - active
+ *             properties:
+ *               subscriberUrl:
+ *                 type: string
+ *                 format: uri
+ *                 description: The URL to subscribe to this webhook
+ *               eventTriggers:
+ *                 type: string
+ *                 enum: [BOOKING_CREATED, BOOKING_RESCHEDULED, BOOKING_CANCELLED, MEETING_ENDED]
+ *                 description: The events which should trigger this webhook call
+ *               active:
+ *                 type: boolean
+ *                 description: Whether the webhook is active and should trigger on associated trigger events
+ *               payloadTemplate:
+ *                 type: string
+ *                 description: The template of the webhook's payload
+ *               eventTypeId:
+ *                 type: number
+ *                 description: The event type ID if this webhook should be associated with only that event type
  *     tags:
  *     - webhooks
  *     externalDocs:
- *        url: https://docs.cal.com/webhooks
+ *        url: https://docs.cal.com/core-features/webhooks
  *     responses:
  *       201:
  *         description: OK, webhook created