mirror of
https://github.com/HabitRPG/habitica.git
synced 2025-12-17 14:47:53 +01:00
chore(docs): Define resource not found errors and permissions
This commit is contained in:
Blade Barringer
@@ -14,7 +14,7 @@ let api = {};
|
||||
|
||||
/**
|
||||
* @apiDefine WebhookNotFound
|
||||
* @apiError (404) {NotFound} WebhookNotFound The specified Webhook could not be found.
|
||||
* @apiError (404) {NotFound} WebhookNotFound The specified webhook could not be found.
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -23,54 +23,54 @@ let api = {};
|
||||
*/
|
||||
|
||||
/**
|
||||
* @api {post} /api/v3/user/webhook Create a new webhook - BETA
|
||||
* @apiName AddWebhook
|
||||
* @apiGroup Webhook
|
||||
*
|
||||
* @apiParam {UUID} [id="Randomly Generated UUID"] Body parameter - The webhook's id
|
||||
* @apiParam {String} url Body parameter - The webhook's URL
|
||||
* @apiParam {String} [label] Body parameter - A label to remind you what this webhook does
|
||||
* @apiParam {Boolean} [enabled=true] Body parameter - If the webhook should be enabled
|
||||
* @apiParam {Sring="taskActivity","groupChatReceived"} [type="taskActivity"] Body parameter - The webhook's type.
|
||||
* @apiParam {Object} [options] Body parameter - The webhook's options. Wil differ depending on type. Required for `groupChatReceived` type. If a webhook supports options, the default values are displayed in the examples below
|
||||
* @apiParamExample {json} Task Activity Example
|
||||
* {
|
||||
* "enabled": true, // default
|
||||
* "url": "http://some-webhook-url.com",
|
||||
* "label": "My Webhook",
|
||||
* "type": "taskActivity", // default
|
||||
* "options": {
|
||||
* "created": false, // default
|
||||
* "updated": false, // default
|
||||
* "deleted": false, // default
|
||||
* "scored": true // default
|
||||
* }
|
||||
* }
|
||||
* @apiParamExample {json} Group Chat Received Example
|
||||
* {
|
||||
* "enabled": true,
|
||||
* "url": "http://some-webhook-url.com",
|
||||
* "label": "My Chat Webhook",
|
||||
* "type": "groupChatReceived",
|
||||
* "options": {
|
||||
* "groupId": "required-uuid-of-group"
|
||||
* }
|
||||
* }
|
||||
* @apiParamExample {json} Minimal Example
|
||||
* {
|
||||
* "url": "http://some-webhook-url.com"
|
||||
* }
|
||||
*
|
||||
* @apiSuccess {Object} data The created webhook
|
||||
* @apiSuccess {UUID} data.id The uuid of the webhook
|
||||
* @apiSuccess {String} data.url The url of the webhook
|
||||
* @apiSuccess {String} data.label A label for you to keep track of what this webhooks is for
|
||||
* @apiSuccess {Boolean} data.enabled Whether the webhook should be sent
|
||||
* @apiSuccess {String} data.type The type of the webhook
|
||||
* @apiSuccess {Object} data.options The options for the webhook (See examples)
|
||||
*
|
||||
* @apiUse WebhookBodyInvalid
|
||||
*/
|
||||
* @api {post} /api/v3/user/webhook Create a new webhook - BETA
|
||||
* @apiName AddWebhook
|
||||
* @apiGroup Webhook
|
||||
*
|
||||
* @apiParam {UUID} [id="Randomly Generated UUID"] Body parameter - The webhook's id
|
||||
* @apiParam {String} url Body parameter - The webhook's URL
|
||||
* @apiParam {String} [label] Body parameter - A label to remind you what this webhook does
|
||||
* @apiParam {Boolean} [enabled=true] Body parameter - If the webhook should be enabled
|
||||
* @apiParam {Sring="taskActivity","groupChatReceived"} [type="taskActivity"] Body parameter - The webhook's type.
|
||||
* @apiParam {Object} [options] Body parameter - The webhook's options. Wil differ depending on type. Required for `groupChatReceived` type. If a webhook supports options, the default values are displayed in the examples below
|
||||
* @apiParamExample {json} Task Activity Example
|
||||
* {
|
||||
* "enabled": true, // default
|
||||
* "url": "http://some-webhook-url.com",
|
||||
* "label": "My Webhook",
|
||||
* "type": "taskActivity", // default
|
||||
* "options": {
|
||||
* "created": false, // default
|
||||
* "updated": false, // default
|
||||
* "deleted": false, // default
|
||||
* "scored": true // default
|
||||
* }
|
||||
* }
|
||||
* @apiParamExample {json} Group Chat Received Example
|
||||
* {
|
||||
* "enabled": true,
|
||||
* "url": "http://some-webhook-url.com",
|
||||
* "label": "My Chat Webhook",
|
||||
* "type": "groupChatReceived",
|
||||
* "options": {
|
||||
* "groupId": "required-uuid-of-group"
|
||||
* }
|
||||
* }
|
||||
* @apiParamExample {json} Minimal Example
|
||||
* {
|
||||
* "url": "http://some-webhook-url.com"
|
||||
* }
|
||||
*
|
||||
* @apiSuccess {Object} data The created webhook
|
||||
* @apiSuccess {UUID} data.id The uuid of the webhook
|
||||
* @apiSuccess {String} data.url The url of the webhook
|
||||
* @apiSuccess {String} data.label A label for you to keep track of what this webhooks is for
|
||||
* @apiSuccess {Boolean} data.enabled Whether the webhook should be sent
|
||||
* @apiSuccess {String} data.type The type of the webhook
|
||||
* @apiSuccess {Object} data.options The options for the webhook (See examples)
|
||||
*
|
||||
* @apiUse WebhookBodyInvalid
|
||||
*/
|
||||
api.addWebhook = {
|
||||
method: 'POST',
|
||||
middlewares: [authWithHeaders()],
|
||||
@@ -96,41 +96,41 @@ api.addWebhook = {
|
||||
};
|
||||
|
||||
/**
|
||||
* @api {put} /api/v3/user/webhook/:id Edit a webhook - BETA
|
||||
* @apiName UserUpdateWebhook
|
||||
* @apiGroup Webhook
|
||||
* @apiDescription Can change `url`, `enabled`, `type`, and `options` properties. Cannot change `id`.
|
||||
*
|
||||
* @apiParam {UUID} id URL parameter - The id of the webhook to update
|
||||
* @apiParam {String} [url] Body parameter - The webhook's URL
|
||||
* @apiParam {String} [label] Body parameter - A label to remind you what this webhook does
|
||||
* @apiParam {Boolean} [enabled] Body parameter - If the webhook should be enabled
|
||||
* @apiParam {Sring="taskActivity","groupChatReceived"} [type] Body parameter - The webhook's type.
|
||||
* @apiParam {Object} [options] Body parameter - The webhook's options. Wil differ depending on type. The options are enumerated in the [add webhook examples](#api-Webhook-UserAddWebhook).
|
||||
* @apiParamExample {json} Update Enabled and Type Properties
|
||||
* {
|
||||
* "enabled": false,
|
||||
* "type": "taskActivity"
|
||||
* }
|
||||
* @apiParamExample {json} Update Group Id for Group Chat Receieved Webhook
|
||||
* {
|
||||
* "options": {
|
||||
* "groupId": "new-uuid-of-group"
|
||||
* }
|
||||
* }
|
||||
*
|
||||
* @apiSuccess {Object} data The updated webhook
|
||||
* @apiSuccess {UUID} data.id The uuid of the webhook
|
||||
* @apiSuccess {String} data.url The url of the webhook
|
||||
* @apiSuccess {String} data.label A label for you to keep track of what this webhooks is for
|
||||
* @apiSuccess {Boolean} data.enabled Whether the webhook should be sent
|
||||
* @apiSuccess {String} data.type The type of the webhook
|
||||
* @apiSuccess {Object} data.options The options for the webhook (See webhook add examples)
|
||||
*
|
||||
* @apiUse WebhookNotFound
|
||||
* @apiUse WebhookBodyInvalid
|
||||
*
|
||||
*/
|
||||
* @api {put} /api/v3/user/webhook/:id Edit a webhook - BETA
|
||||
* @apiName UserUpdateWebhook
|
||||
* @apiGroup Webhook
|
||||
* @apiDescription Can change `url`, `enabled`, `type`, and `options` properties. Cannot change `id`.
|
||||
*
|
||||
* @apiParam {UUID} id URL parameter - The id of the webhook to update
|
||||
* @apiParam {String} [url] Body parameter - The webhook's URL
|
||||
* @apiParam {String} [label] Body parameter - A label to remind you what this webhook does
|
||||
* @apiParam {Boolean} [enabled] Body parameter - If the webhook should be enabled
|
||||
* @apiParam {Sring="taskActivity","groupChatReceived"} [type] Body parameter - The webhook's type.
|
||||
* @apiParam {Object} [options] Body parameter - The webhook's options. Wil differ depending on type. The options are enumerated in the [add webhook examples](#api-Webhook-UserAddWebhook).
|
||||
* @apiParamExample {json} Update Enabled and Type Properties
|
||||
* {
|
||||
* "enabled": false,
|
||||
* "type": "taskActivity"
|
||||
* }
|
||||
* @apiParamExample {json} Update Group Id for Group Chat Receieved Webhook
|
||||
* {
|
||||
* "options": {
|
||||
* "groupId": "new-uuid-of-group"
|
||||
* }
|
||||
* }
|
||||
*
|
||||
* @apiSuccess {Object} data The updated webhook
|
||||
* @apiSuccess {UUID} data.id The uuid of the webhook
|
||||
* @apiSuccess {String} data.url The url of the webhook
|
||||
* @apiSuccess {String} data.label A label for you to keep track of what this webhooks is for
|
||||
* @apiSuccess {Boolean} data.enabled Whether the webhook should be sent
|
||||
* @apiSuccess {String} data.type The type of the webhook
|
||||
* @apiSuccess {Object} data.options The options for the webhook (See webhook add examples)
|
||||
*
|
||||
* @apiUse WebhookNotFound
|
||||
* @apiUse WebhookBodyInvalid
|
||||
*
|
||||
*/
|
||||
api.updateWebhook = {
|
||||
method: 'PUT',
|
||||
middlewares: [authWithHeaders()],
|
||||
|
||||
Reference in New Issue
Block a user