diff --git a/website/server/api-doc.js b/website/server/api-doc.js new file mode 100644 index 0000000000..cc798c26db --- /dev/null +++ b/website/server/api-doc.js @@ -0,0 +1,15 @@ +'use strict'; + +// This file defines some globals for use in the API Doc comments + +/** + * @apiDefine Path Path Parameters + */ + +/** + * @apiDefine Body Body Parameters + */ + +/** + * @apiDefine Query Query Parameters + */ diff --git a/website/server/controllers/api-v3/groups.js b/website/server/controllers/api-v3/groups.js index 009944aedb..a638c819be 100644 --- a/website/server/controllers/api-v3/groups.js +++ b/website/server/controllers/api-v3/groups.js @@ -672,12 +672,12 @@ async function _inviteByEmail (invite, group, inviter, req, res) { * @apiGroup Group * @apiDescription You can provide both `emails` and `uuids`, or just one. You must provide at least one. * - * @apiParam {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted) + * @apiParam (Path) {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted) * - * @apiParam {Object[]} [emails] Body parameter - An array of objects, each representing one email address to invite - * @apiParam {String} emails.email The email address of the user being invited. - * @apiParam {String} [emails.name] The name of the user being invited. - * @apiParam {Array} [uuids] Body parameter - An array of uuids to invite + * @apiParam (Body) {Object[]} [emails] An array of objects, each representing one email address to invite + * @apiParam (Body) {String} emails.email The email address of the user being invited. + * @apiParam (Body) {String} [emails.name] The name of the user being invited. + * @apiParam (Body) {Array} [uuids] An array of uuids to invite * * @apiParamExample {json} Emails * { @@ -706,24 +706,24 @@ async function _inviteByEmail (invite, group, inviter, req, res) { * @apiSuccessExample {json} Successful Response with Emails * { * "data": [ - * "user-1@example.com", - * "user-2@exmaple.com" + * "user-1@example.com", + * "user-2@exmaple.com" * ] * } * * @apiSuccessExample {json} Successful Response with User Id * { - * "data": [ - * { id: 'the-id-of-the-invited-user', name: 'The group name', inviter: 'your-user-id' } - * ] + * "data": [ + * { id: 'the-id-of-the-invited-user', name: 'The group name', inviter: 'your-user-id' } + * ] * } * @apiSuccessExample {json} Successful Response with User Ids and Emails * { - * "data": [ - * "user-1@example.com", - * { id: 'the-id-of-the-invited-user', name: 'The group name', inviter: 'your-user-id' }, - * "user-2@exmaple.com" - * ] + * "data": [ + * "user-1@example.com", + * { id: 'the-id-of-the-invited-user', name: 'The group name', inviter: 'your-user-id' }, + * "user-2@exmaple.com" + * ] * } * * @apiUse GroupBodyInvalid diff --git a/website/server/controllers/api-v3/webhook.js b/website/server/controllers/api-v3/webhook.js index b6c0f35ec9..0456159639 100644 --- a/website/server/controllers/api-v3/webhook.js +++ b/website/server/controllers/api-v3/webhook.js @@ -27,12 +27,12 @@ let api = {}; * @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 + * @apiParam (Body) {UUID} [id="Randomly Generated UUID"] The webhook's id + * @apiParam (Body) {String} url The webhook's URL + * @apiParam (Body) {String} [label] A label to remind you what this webhook does + * @apiParam (Body) {Boolean} [enabled=true] If the webhook should be enabled + * @apiParam (Body) {Sring="taskActivity","groupChatReceived"} [type="taskActivity"] The webhook's type. + * @apiParam (Body) {Object} [options] 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 @@ -101,12 +101,12 @@ api.addWebhook = { * @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). + * @apiParam (Path) {UUID} id URL parameter - The id of the webhook to update + * @apiParam (Body) {String} [url] The webhook's URL + * @apiParam (Body) {String} [label] A label to remind you what this webhook does + * @apiParam (Body) {Boolean} [enabled] If the webhook should be enabled + * @apiParam (Body) {Sring="taskActivity","groupChatReceived"} [type] The webhook's type. + * @apiParam (Body) {Object} [options] 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, @@ -177,7 +177,7 @@ api.updateWebhook = { * @apiName UserDeleteWebhook * @apiGroup Webhook * -* @apiParam {UUID} id The id of the webhook to delete +* @apiParam (Path) {UUID} id The id of the webhook to delete * * @apiSuccess {Array} data The remaining webhooks for the user * @apiUse WebhookNotFound