From a76eacb52bb55ae083c18bac0a5b4b8008a8ae42 Mon Sep 17 00:00:00 2001
From: AntonyAntonio <guillermo@opensupports.com>
Date: Fri, 21 Apr 2017 22:33:17 -0300
Subject: [PATCH] Guillermo -   things [skip ci]

---
 server/controllers/article/add-topic.php         | 3 ++-
 server/controllers/article/add.php               | 4 ++--
 server/controllers/article/get-all.php           | 3 +--
 server/controllers/staff/add.php                 | 3 ++-
 server/controllers/staff/get-all-tickets.php     | 4 +++-
 server/controllers/staff/get-all.php             | 2 +-
 server/controllers/staff/get-new-tickets.php     | 2 +-
 server/controllers/staff/get-tickets.php         | 2 +-
 server/controllers/staff/get.php                 | 9 ++++++++-
 server/controllers/staff/last-events.php         | 2 +-
 server/controllers/staff/search-tickets.php      | 4 +++-
 server/controllers/system/add-api-key.php        | 2 +-
 server/controllers/system/add-department.php     | 2 +-
 server/controllers/system/backup-database.php    | 2 ++
 server/controllers/system/csv-import.php         | 3 ++-
 server/controllers/system/get-api-keys.php       | 2 +-
 server/controllers/system/get-logs.php           | 2 +-
 server/controllers/system/get-mail-templates.php | 2 +-
 server/controllers/system/get-settings.php       | 2 +-
 server/controllers/system/get-stats.php          | 2 +-
 server/controllers/ticket/check.php              | 4 +++-
 server/controllers/ticket/create.php             | 3 ++-
 server/controllers/ticket/seen.php               | 2 +-
 server/controllers/user/ban.php                  | 2 +-
 server/controllers/user/check-session.php        | 5 +++--
 server/controllers/user/delete.php               | 2 +-
 server/controllers/user/get-user.php             | 7 ++++++-
 server/controllers/user/get-users.php            | 7 ++++++-
 server/controllers/user/get.php                  | 7 ++++++-
 server/controllers/user/list-ban.php             | 2 +-
 server/controllers/user/login.php                | 7 ++++++-
 server/controllers/user/signup.php               | 4 +++-
 server/controllers/user/verify.php               | 2 +-
 server/models/Department.php                     | 2 +-
 server/models/Staff.php                          | 4 ++--
 server/models/Topic.php                          | 2 +-
 36 files changed, 80 insertions(+), 39 deletions(-)

diff --git a/server/controllers/article/add-topic.php b/server/controllers/article/add-topic.php
index 64065e53..90e0b831 100644
--- a/server/controllers/article/add-topic.php
+++ b/server/controllers/article/add-topic.php
@@ -20,7 +20,8 @@ DataValidator::with('CustomValidations', true);
  * @apiUse NO_PERMISSION
  * @apiUse INVALID_NAME
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Topic info
+ * @apiSuccess {Number} data.topicId Topic id
  *
  */
 
diff --git a/server/controllers/article/add.php b/server/controllers/article/add.php
index 19439e11..52a9d954 100644
--- a/server/controllers/article/add.php
+++ b/server/controllers/article/add.php
@@ -23,8 +23,8 @@ DataValidator::with('CustomValidations', true);
  * @apiUse INVALID_CONTENT
  * @apiUse INVALID_TOPIC
  *
- * @apiSuccess {Object} data
- *
+ * @apiSuccess {Object} data Article info
+ * @apiSuccess {Number} data.articleId Article id
  */
 
 class AddArticleController extends Controller {
diff --git a/server/controllers/article/get-all.php b/server/controllers/article/get-all.php
index 35e49357..a2031c1e 100644
--- a/server/controllers/article/get-all.php
+++ b/server/controllers/article/get-all.php
@@ -15,8 +15,7 @@ DataValidator::with('CustomValidations', true);
  *
  * @apiUse NO_PERMISSION
  * 
- * @apiSuccess {Object} data
- *
+ * @apiSuccess {[Topic](#api-Data_Structures-ObjectTopic)[]} data Array of topics.
  */
 
 class GetAllArticlesController extends Controller {
diff --git a/server/controllers/staff/add.php b/server/controllers/staff/add.php
index cd809879..2c4ccc07 100644
--- a/server/controllers/staff/add.php
+++ b/server/controllers/staff/add.php
@@ -27,7 +27,8 @@ DataValidator::with('CustomValidations', true);
  * @apiUse INVALID_LEVEL
  * @apiUse ALREADY_A_STAFF
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Staff info object
+ * @apiSuccess {Number} data.id Staff id
  *
  */
 
diff --git a/server/controllers/staff/get-all-tickets.php b/server/controllers/staff/get-all-tickets.php
index 90956f21..8cf367ac 100644
--- a/server/controllers/staff/get-all-tickets.php
+++ b/server/controllers/staff/get-all-tickets.php
@@ -17,7 +17,9 @@ use Respect\Validation\Validator as DataValidator;
  * @apiUse NO_PERMISSION
  * @apiUse INVALID_PAGE
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Information about a tickets and quantity of pages
+ * @apiSuccess {[Ticket](#api-Data_Structures-ObjectTicket)[]} data.tickets Array of tickets of the current page
+ * @apiSuccess {Number} data.pages Quantity of pages
  *
  */
 
diff --git a/server/controllers/staff/get-all.php b/server/controllers/staff/get-all.php
index ce656906..9ea663aa 100644
--- a/server/controllers/staff/get-all.php
+++ b/server/controllers/staff/get-all.php
@@ -14,7 +14,7 @@ use Respect\Validation\Validator as DataValidator;
  * 
  * @apiUse NO_PERMISSION
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {[Staff](#api-Data_Structures-ObjectStaff)[]} data Array of staff members.
  *
  */
 
diff --git a/server/controllers/staff/get-new-tickets.php b/server/controllers/staff/get-new-tickets.php
index e36ba3eb..ddfb439a 100644
--- a/server/controllers/staff/get-new-tickets.php
+++ b/server/controllers/staff/get-new-tickets.php
@@ -15,7 +15,7 @@ use Respect\Validation\Validator as DataValidator;
  *
  * @apiUse NO_PERMISSION
  * 
- * @apiSuccess {Object} data
+ * @apiSuccess {[Ticket](#api-Data_Structures-ObjectTicket)[]} data Array of new tickets
  *
  */
 
diff --git a/server/controllers/staff/get-tickets.php b/server/controllers/staff/get-tickets.php
index 352bca6a..03b42950 100644
--- a/server/controllers/staff/get-tickets.php
+++ b/server/controllers/staff/get-tickets.php
@@ -14,7 +14,7 @@ use Respect\Validation\Validator as DataValidator;
  *
  * @apiUse NO_PERMISSION
  * 
- * @apiSuccess {Object} data
+ * @apiSuccess {[Ticket](#api-Data_Structures-ObjectTicket)[]} data Array of tickets assigned to the staff
  *
  */
 
diff --git a/server/controllers/staff/get.php b/server/controllers/staff/get.php
index e42eee21..a0737992 100644
--- a/server/controllers/staff/get.php
+++ b/server/controllers/staff/get.php
@@ -17,7 +17,14 @@ DataValidator::with('CustomValidations', true);
  * 
  * @apiUse NO_PERMISSION
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Information about a staff member
+ * @apiSuccess {String} data.name Staff id
+ * @apiSuccess {String} data.email Staff id
+ * @apiSuccess {String} data.profilePic Staff id
+ * @apiSuccess {Number} data.level Staff id
+ * @apiSuccess {Boolean} data.staff Staff id
+ * @apiSuccess {[Department](#api-Data_Structures-ObjectDepartment)[]} data.departments Array of departments that has assigned.
+ * @apiSuccess {[Ticket](#api-Data_Structures-ObjectTicket)[]} data.tickets Array of tickets that has assigned.
  *
  */
 
diff --git a/server/controllers/staff/last-events.php b/server/controllers/staff/last-events.php
index 6652b8b2..b166bd5d 100644
--- a/server/controllers/staff/last-events.php
+++ b/server/controllers/staff/last-events.php
@@ -17,7 +17,7 @@ use Respect\Validation\Validator as DataValidator;
  * @apiUse NO_PERMISSION
  * @apiUse INVALID_PAGE
  * 
- * @apiSuccess {Object} data
+ * @apiSuccess {[TicketEvent](#api-Data_Structures-ObjectTicketevent)[]} data Array of last events
  *
  */
 
diff --git a/server/controllers/staff/search-tickets.php b/server/controllers/staff/search-tickets.php
index c6c166df..7c3e5a72 100644
--- a/server/controllers/staff/search-tickets.php
+++ b/server/controllers/staff/search-tickets.php
@@ -19,7 +19,9 @@ use Respect\Validation\Validator as DataValidator;
  * @apiUse INVALID_QUERY
  * @apiUse INVALID_PAGE
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Information about tickets
+ * @apiSuccess {[Ticket](#api-Data_Structures-ObjectTicket)[]} data.tickets Array of tickets found
+ * @apiSuccess {Number} data.pages Number of the page
  *
  */
 
diff --git a/server/controllers/system/add-api-key.php b/server/controllers/system/add-api-key.php
index 26e2d966..88732751 100644
--- a/server/controllers/system/add-api-key.php
+++ b/server/controllers/system/add-api-key.php
@@ -18,7 +18,7 @@ use Respect\Validation\Validator as DataValidator;
  * @apiUse INVALID_NAME
  * @apiUse NAME_ALREADY_USED
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {String} data Token of the api key
  *
  */
 
diff --git a/server/controllers/system/add-department.php b/server/controllers/system/add-department.php
index 9bdfbaea..47a10fc8 100644
--- a/server/controllers/system/add-department.php
+++ b/server/controllers/system/add-department.php
@@ -17,7 +17,7 @@ use Respect\Validation\Validator as DataValidator;
  * @apiUse NO_PERMISSION
  * @apiUse INVALID_NAME
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Empty object
  *
  */
 
diff --git a/server/controllers/system/backup-database.php b/server/controllers/system/backup-database.php
index 0e10a7e9..80f03546 100644
--- a/server/controllers/system/backup-database.php
+++ b/server/controllers/system/backup-database.php
@@ -13,6 +13,8 @@ use Ifsnop\Mysqldump as IMysqldump;
  * @apiPermission Staff level 3
  *
  * @apiUse NO_PERMISSION
+ * 
+ * @apiSuccess {File} file File of the backup
  *
  */
 
diff --git a/server/controllers/system/csv-import.php b/server/controllers/system/csv-import.php
index 0c26a4cb..e32d4bb9 100644
--- a/server/controllers/system/csv-import.php
+++ b/server/controllers/system/csv-import.php
@@ -14,8 +14,9 @@
  * @apiParam {String} file A csv file with this content format: email,password, name.
  *
  * @apiUse NO_PERMISSION
+ * @apiUse INVALID_FILE
  * 
- * @apiSuccess {Object} data
+ * @apiSuccess {String[]} data Array of errors found
  *
  */
 
diff --git a/server/controllers/system/get-api-keys.php b/server/controllers/system/get-api-keys.php
index c710055b..46af5bfe 100644
--- a/server/controllers/system/get-api-keys.php
+++ b/server/controllers/system/get-api-keys.php
@@ -14,7 +14,7 @@ use Respect\Validation\Validator as DataValidator;
  *
  * @apiUse NO_PERMISSION
  * 
- * @apiSuccess {Object} data
+ * @apiSuccess {[APIKey](#api-Data_Structures-ObjectApikey)[]} data Array of api keys
  *
  */
 
diff --git a/server/controllers/system/get-logs.php b/server/controllers/system/get-logs.php
index 4b769a39..eb9c7135 100644
--- a/server/controllers/system/get-logs.php
+++ b/server/controllers/system/get-logs.php
@@ -17,7 +17,7 @@ use Respect\Validation\Validator as DataValidator;
  * @apiUse NO_PERMISSION
  * @apiUse INVALID_PAGE
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {[Log](#api-Data_Structures-ObjectLog)[]} data Array of last logs
  *
  */
 
diff --git a/server/controllers/system/get-mail-templates.php b/server/controllers/system/get-mail-templates.php
index 56609777..e448ca35 100644
--- a/server/controllers/system/get-mail-templates.php
+++ b/server/controllers/system/get-mail-templates.php
@@ -14,7 +14,7 @@ use Respect\Validation\Validator as DataValidator;
  *
  * @apiUse NO_PERMISSION
  * 
- * @apiSuccess {Object} data
+ * @apiSuccess {[MailTemplate](#api-Data_Structures-ObjectMailtemplate)[]} data Array of mail templates
  *
  */
 
diff --git a/server/controllers/system/get-settings.php b/server/controllers/system/get-settings.php
index 66c53d8b..5e9fca81 100644
--- a/server/controllers/system/get-settings.php
+++ b/server/controllers/system/get-settings.php
@@ -13,7 +13,7 @@
  *
  * @apiParam {Boolean} allSettings A bool that means if you want a regular settings list or a complety settings list.
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Contains the information about the settings
  *
  */
 
diff --git a/server/controllers/system/get-stats.php b/server/controllers/system/get-stats.php
index a27ce258..c52bcb08 100644
--- a/server/controllers/system/get-stats.php
+++ b/server/controllers/system/get-stats.php
@@ -18,7 +18,7 @@ use Respect\Validation\Validator as DataValidator;
  * @apiUse NO_PERMISSION
  * @apiUse INVALID_PERIOD
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {[StatList](#api-Data_Structures-ObjectStatlist)[]} data Array of the stats
  *
  */
 
diff --git a/server/controllers/ticket/check.php b/server/controllers/ticket/check.php
index 3d2af299..084a2609 100644
--- a/server/controllers/ticket/check.php
+++ b/server/controllers/ticket/check.php
@@ -22,7 +22,9 @@ DataValidator::with('CustomValidations', true);
  * @apiUse INVALID_CAPTCHA 
  * @apiUse NO_PERMISSION
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Data for the ticket session
+ * @apiSuccess {String} data.token Token of the ticket session
+ * @apiSuccess {Number} data.ticketNumber Number of the ticket 
  *
  */
 
diff --git a/server/controllers/ticket/create.php b/server/controllers/ticket/create.php
index ab5fa3da..b5f2e788 100644
--- a/server/controllers/ticket/create.php
+++ b/server/controllers/ticket/create.php
@@ -27,7 +27,8 @@ DataValidator::with('CustomValidations', true);
  * @apiUse INVALID_LANGUAGE
  * @apiUse INVALID_CAPTCHA
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Information of the new ticket
+ * @apiSuccess {Number} data.ticketNumber Number of the new ticket
  *
  */
 
diff --git a/server/controllers/ticket/seen.php b/server/controllers/ticket/seen.php
index 220f2a62..a0f193ca 100644
--- a/server/controllers/ticket/seen.php
+++ b/server/controllers/ticket/seen.php
@@ -17,7 +17,7 @@ use Respect\Validation\Validator as DataValidator;
  * @apiUse NO_PERMISSION
  * @apiUse INVALID_TICKET
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Empty object
  *
  */
 
diff --git a/server/controllers/user/ban.php b/server/controllers/user/ban.php
index 5ee0deeb..03420bb5 100644
--- a/server/controllers/user/ban.php
+++ b/server/controllers/user/ban.php
@@ -18,7 +18,7 @@ use Respect\Validation\Validator as DataValidator;
  * @apiUse INVALID_EMAIL
  * @apiUse ALREADY_BANNED
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Empty object
  *
  */
 class BanUserController extends Controller {
diff --git a/server/controllers/user/check-session.php b/server/controllers/user/check-session.php
index 66242f1f..fff3860f 100644
--- a/server/controllers/user/check-session.php
+++ b/server/controllers/user/check-session.php
@@ -7,11 +7,12 @@
  *
  * @apiGroup User
  *
- * @apiDescription This path give back a object that says if a session exist or not.
+ * @apiDescription This path retrieves a object that says if a session exist or not.
  *
  * @apiPermission Any
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Information about the session
+ * @apiSuccess {Boolean} data.sessionActive Indicate if the session is activated 
  *
  */
 
diff --git a/server/controllers/user/delete.php b/server/controllers/user/delete.php
index 402edf57..83f8f26f 100644
--- a/server/controllers/user/delete.php
+++ b/server/controllers/user/delete.php
@@ -19,7 +19,7 @@ use RedBeanPHP\Facade as RedBean;
  * @apiUse INVALID_USER
  * @apiUse USER_SYSTEM_DISABLED
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Empty object
  *
  */
 
diff --git a/server/controllers/user/get-user.php b/server/controllers/user/get-user.php
index bfedf8cb..afa6ab1c 100644
--- a/server/controllers/user/get-user.php
+++ b/server/controllers/user/get-user.php
@@ -19,7 +19,12 @@ DataValidator::with('CustomValidations', true);
  * @apiUse INVALID_USER
  * @apiUse USER_SYSTEM_DISABLED
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Information about a user
+ * @apiSuccess {String} data.name Name of the user
+ * @apiSuccess {String} data.email Email of the user
+ * @apiSuccess {Number} data.signupDate Date of signup of the user
+ * @apiSuccess {[Ticket](#api-Data_Structures-ObjectTicket)[]} data.tickets Array of tickets of the user
+ * @apiSuccess {Boolean} data.verified Indicates if the user is verified
  *
  */
 
diff --git a/server/controllers/user/get-users.php b/server/controllers/user/get-users.php
index d8bca578..2cea2f71 100644
--- a/server/controllers/user/get-users.php
+++ b/server/controllers/user/get-users.php
@@ -23,7 +23,12 @@ use Respect\Validation\Validator as DataValidator;
  * @apiUse USER_SYSTEM_DISABLED
  *
  * @apiSuccess {Object} data
- *
+ * @apiSuccess {[User](#api-Data_Structures-ObjectUser)[]} data.users Array of users found
+ * @apiSuccess {Number} data.pages Number of pages found
+ * @apiSuccess {Number} data.page Number of the page
+ * @apiSuccess {String} data.orderBy Indicates if it's ordered by id or quantity of tickets
+ * @apiSuccess {Boolean} data.desc Indicates if it's ordered in decreasing order
+ * @apiSuccess {String} data.search Query of the search
  */
 
 class GetUsersController extends Controller {
diff --git a/server/controllers/user/get.php b/server/controllers/user/get.php
index adb69cd3..6bacfa6b 100644
--- a/server/controllers/user/get.php
+++ b/server/controllers/user/get.php
@@ -16,7 +16,12 @@ DataValidator::with('CustomValidations', true);
  * @apiUse NO_PERMISSION
  * @apiUse INVALID_CREDENTIALS
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Information about a user
+ * @apiSuccess {String} data.name Name of the user 
+ * @apiSuccess {String} data.email Email of the user
+ * @apiSuccess {Boolean} data.verified Indicates if the user is verified
+ * @apiSuccess {Object} data Information about a user
+ * @apiSuccess {[Ticket](#api-Data_Structures-ObjectTicket)[]} data.tickets Array of tickets of the user
  *
  */
 
diff --git a/server/controllers/user/list-ban.php b/server/controllers/user/list-ban.php
index 1a0d2e81..8ff7e2ae 100644
--- a/server/controllers/user/list-ban.php
+++ b/server/controllers/user/list-ban.php
@@ -14,7 +14,7 @@ use Respect\Validation\Validator as DataValidator;
  *
  * @apiUse NO_PERMISSION
  * 
- * @apiSuccess {Object} data
+ * @apiSuccess {[Ban](#api-Data_Structures-ObjectBan)[]} data Array of emails banned
  *
  */
 
diff --git a/server/controllers/user/login.php b/server/controllers/user/login.php
index 3e5ddcbd..102edbc7 100644
--- a/server/controllers/user/login.php
+++ b/server/controllers/user/login.php
@@ -23,7 +23,12 @@
  * @apiUse UNVERIFIED_USER
  * @apiUse INVALID_CREDENTIALS
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Information about the session
+ * @apiSuccess {Number} data.userId Id of the user 
+ * @apiSuccess {String} data.userEmail Email of the user
+ * @apiSuccess {Boolean} data.staff Indicates if the user is staff or not
+ * @apiSuccess {String} data.token Token of the session, used to verify the session when making other requests 
+ * @apiSuccess {String} data.rememberToken Token of the remember session for automatic login  
  *
  */
 
diff --git a/server/controllers/user/signup.php b/server/controllers/user/signup.php
index 110d4405..b36b96fe 100644
--- a/server/controllers/user/signup.php
+++ b/server/controllers/user/signup.php
@@ -28,7 +28,9 @@ DataValidator::with('CustomValidations', true);
  * @apiUse ALREADY_BANNED
  * @apiUse NO_PERMISSION
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Information about created user
+ * @apiSuccess {Number} data.userId Id of the new user
+ * @apiSuccess {String} data.userEmail Email of the new user
  *
  */
 
diff --git a/server/controllers/user/verify.php b/server/controllers/user/verify.php
index 689282ca..7abbb380 100644
--- a/server/controllers/user/verify.php
+++ b/server/controllers/user/verify.php
@@ -19,7 +19,7 @@ use Respect\Validation\Validator as DataValidator;
  * @apiUse USER_SYSTEM_DISABLED
  * @apiUse INVALID_TOKEN
  *
- * @apiSuccess {Object} data
+ * @apiSuccess {Object} data Empty object
  *
  */
 
diff --git a/server/models/Department.php b/server/models/Department.php
index 70fa262a..7a3818b0 100644
--- a/server/models/Department.php
+++ b/server/models/Department.php
@@ -6,7 +6,7 @@ use RedBeanPHP\Facade as RedBean;
  * @apiGroup Data Structures
  * @apiParam {Number} id Id of the custom response.
  * @apiParam {String} name Name of the custom response.
- * @apiParam {String} owners Owners of the department.
+ * @apiParam {[Staff](#api-Data_Structures-ObjectStaff)[]} owners Owners of the department.
  */
 
 class Department extends DataStore {
diff --git a/server/models/Staff.php b/server/models/Staff.php
index b24f4493..c31c0209 100644
--- a/server/models/Staff.php
+++ b/server/models/Staff.php
@@ -7,8 +7,8 @@
  * @apiParam {String} email The language of the mail template.
  * @apiParam {String} profilePic The body of the mail template.
  * @apiParam {Number} level The language of the mail template.
- * @apiParam {Object} departments The department of the staff.
- * @apiParam {Object} tickets The tickets of the staff.
+ * @apiParam {Object[]} departments The departments of the staff.
+ * @apiParam {[Ticket](#api-Data_Structures-ObjectTicket)[]} tickets The tickets of the staff.
  * @apiParam {Number} lastLogin The last login of the staff.
  */
 
diff --git a/server/models/Topic.php b/server/models/Topic.php
index 0fb76eba..f28a669d 100644
--- a/server/models/Topic.php
+++ b/server/models/Topic.php
@@ -6,7 +6,7 @@
  * @apiParam {String} name Name of the topic.
  * @apiParam {String} icon Icon of the topic.
  * @apiParam {String} iconColor Icon's color of the topic.
- * @apiParam {Object} articles Articles of the Topic.
+ * @apiParam {[Article](#api-Data_Structures-ObjectArticle)[]} articles Articles of the Topic.
  */
 
 class Topic extends DataStore {