From e271e57f63da84a04eb74561907b6846be953fea Mon Sep 17 00:00:00 2001
From: Julie Torres <reeddetorres@gmail.com>
Date: Sun, 2 Oct 2016 19:17:14 -0400
Subject: [PATCH] Improve API Docs for Invite to Group, Iss#8087

---
 website/server/controllers/api-v3/groups.js | 69 ++++++++++++++++-----
 1 file changed, 52 insertions(+), 17 deletions(-)

diff --git a/website/server/controllers/api-v3/groups.js b/website/server/controllers/api-v3/groups.js
index 48acb8269e..4a5157d6c8 100644
--- a/website/server/controllers/api-v3/groups.js
+++ b/website/server/controllers/api-v3/groups.js
@@ -21,6 +21,11 @@ import { encrypt } from '../../libs/encryption';
 import { sendNotification as sendPushNotification } from '../../libs/pushNotifications';
 import pusher from '../../libs/pusher';
 
+/**
+ * @apiDefine GroupBodyInvalid
+ * @apiError (400) {BadRequest} GroupBodyInvalid A parameter in the group body was invalid.
+ */
+
 /**
  * @apiDefine GroupNotFound
  * @apiError (404) {NotFound} GroupNotFound The specified group could not be found.
@@ -669,38 +674,68 @@ async function _inviteByEmail (invite, group, inviter, req, res) {
  *
  * @apiParam {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted)
  *
- * @apiParam {Array} [emails] Body parameter - An array of emails addresses to invite
+ * @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
  *
  * @apiParamExample {json} Emails
- *   {
- *     "emails": ["user-1@example.com", "user-2@exmaple.com"]
- *   }
+ * {
+ *    "emails": [
+ *      {"email": "user-1@example.com"},
+ *      {"name": "User2", "email": "user-2@example.com"}
+ *    ]
+ * }
  * @apiParamExample {json} User Ids
  *   {
  *     "uuids": ["user-id-of-existing-user", "user-id-of-another-existing-user"]
  *   }
  * @apiParamExample {json} User Ids and Emails
- *   {
- *     "emails": ["user-1@example.com", "user-2@exmaple.com"],
- *     "uuids": ["user-id-of-existing-user", "user-id-of-another-existing-user"],
- *   }
+ * {
+ *   "emails": [
+ *       {"email": "user-1@example.com"},
+ *       {"email": "user-2@example.com"}
+ *   ],
+ *   "uuids": ["user-id-of-existing-user"]
+ * }
  *
  * @apiSuccess {Array} data The invites
  * @apiSuccess {Object} data[0] If the invitation was a user id, you'll receive back an object. You'll recieve one Object for each succesful user id invite.
  * @apiSuccess {String} data[1] If the invitation was an email, you'll receive back the email. You'll recieve one String for each successful email invite.
  *
- * @apiSuccessExample {json} Successful Response
- *   {
- *     data: [
- *       { id: 'the-id-of-the-invited-user', name: 'The group name', inviter: 'your-user-id' },
- *       "user@example.com"
- *     ]
- *   }
+ * @apiSuccessExample {json} Successful Response with Emails
+ * {
+ *   "data": [
+ *       "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' }
+ *     ]
+ * }
+ *
+ * @apiUse GroupBodyInvalid
  * @apiUse GroupNotFound
- * @apiError InvalidInvitationParams An error relating to the data sent in `emails` and/or `uuids`
- * @apiError TooManyInvites A max of 100 invites (combined emails and user ids) can be sent out at a time
+ * @apiUse UserNotFound
+ * @apiError (400) {BadRequest} NoEmailProvided An email address was not provided in the `emails` body param
+ * @apiUse PartyNotFound
+ * @apiError (400) {BadRequest} UuidOrEmailOnly The `emails` and `uuids` params
+ * were both missing and/or a key other than `emails` or `uuids` was provided in
+ * the body param.
+ * @apiError (400) {BadRequest} CannotInviteSelf User id or email of invitee matches that
+ * of inviter.
+ * @apiError (401) {NotAuthorized} UserAlreadyInvited The user has already been
+ * invited to the group.
+ * @apiError (401) {NotAuthorized} UserAlreadyInGroup The user is already a member
+ * of the group.
+ * @apiError (400) {BadRequest} MustBeArray The `uuids` or `emails` body param is
+ * not an array.
+ * match a valid user.
+ * @apiError (400) {BadRequest} TooManyInvites A max of 100 invites (combined emails and user ids) can be sent out at a time
  */
 api.inviteToGroup = {
   method: 'POST',