From 81e9c632b30e8f3570b9edd8b01db5d13f2e0ccd Mon Sep 17 00:00:00 2001
From: AntonyAntonio <guillermo@opensupports.com>
Date: Sun, 16 Apr 2017 02:35:04 -0300
Subject: [PATCH] Guillermo -   data user [skip ci]

---
 server/controllers/user/ban.php               | 18 ++++++++++++
 server/controllers/user/check-session.php     | 17 +++++++++++
 server/controllers/user/delete.php            | 19 ++++++++++++
 server/controllers/user/edit-email.php        | 19 ++++++++++++
 server/controllers/user/edit-password.php     | 21 ++++++++++++++
 server/controllers/user/get-user.php          | 19 ++++++++++++
 server/controllers/user/get-users.php         | 25 ++++++++++++++++
 server/controllers/user/get.php               | 17 +++++++++++
 server/controllers/user/list-ban.php          | 15 ++++++++++
 server/controllers/user/login.php             | 29 +++++++++++++++++++
 server/controllers/user/logout.php            | 14 +++++++++
 server/controllers/user/recover-password.php  | 23 +++++++++++++++
 .../user/send-recover-password.php            | 19 ++++++++++++
 server/controllers/user/signup.php            | 25 ++++++++++++++++
 server/controllers/user/un-ban.php            | 19 ++++++++++++
 server/controllers/user/verify.php            | 21 ++++++++++++++
 16 files changed, 320 insertions(+)

diff --git a/server/controllers/user/ban.php b/server/controllers/user/ban.php
index 4cc903b7..3c3d50f2 100644
--- a/server/controllers/user/ban.php
+++ b/server/controllers/user/ban.php
@@ -1,6 +1,24 @@
 <?php
 use Respect\Validation\Validator as DataValidator;
 
+/**
+ * @api {post} /user/ban Bans email users
+ *
+ * @apiName BanUser
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path takes an Email and bans it.
+ *
+ * @apiPermission Staff Level 1
+ * 
+ * @apiParam {String} email email of user to ban.
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
 class BanUserController extends Controller {
     const PATH = '/ban';
     const METHOD = 'POST';
diff --git a/server/controllers/user/check-session.php b/server/controllers/user/check-session.php
index 750bddcd..4aa26c48 100644
--- a/server/controllers/user/check-session.php
+++ b/server/controllers/user/check-session.php
@@ -1,5 +1,22 @@
 <?php
 
+/**
+ * @api {post} /user/check-session check if session exist or not
+ *
+ * @apiName check-session
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path give back a object that says if a session exist or not.
+ *
+ * @apiPermission Any
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 class CheckSessionController extends Controller {
     const PATH = '/check-session';
     const METHOD = 'POST';
diff --git a/server/controllers/user/delete.php b/server/controllers/user/delete.php
index 6d935f45..3279268f 100644
--- a/server/controllers/user/delete.php
+++ b/server/controllers/user/delete.php
@@ -2,6 +2,25 @@
 use Respect\Validation\Validator as DataValidator;
 use RedBeanPHP\Facade as RedBean;
 
+/**
+ * @api {post} /user/delete Delete a user
+ *
+ * @apiName delete
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path receive a user id and delete its user.
+ *
+ * @apiPermission Staff level 1
+ *
+ * @apiParam {number} userId the id of the user to delete
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 DataValidator::with('CustomValidations', true);
 
 class DeleteUserController extends Controller {
diff --git a/server/controllers/user/edit-email.php b/server/controllers/user/edit-email.php
index dc7793d6..4f08c9e2 100644
--- a/server/controllers/user/edit-email.php
+++ b/server/controllers/user/edit-email.php
@@ -1,6 +1,25 @@
 <?php
 use Respect\Validation\Validator as DataValidator;
 
+/**
+ * @api {post} /user/edit-email Edit email of an user.
+ *
+ * @apiName edit-email
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path change the email of a user.
+ *
+ * @apiPermission User
+ *
+ * @apiParam {string} newEmail the new email that the user wants to change
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 class EditEmail extends Controller{
     const PATH = '/edit-email';
     const METHOD = 'POST';
diff --git a/server/controllers/user/edit-password.php b/server/controllers/user/edit-password.php
index 07a56b99..de090b8a 100644
--- a/server/controllers/user/edit-password.php
+++ b/server/controllers/user/edit-password.php
@@ -1,6 +1,27 @@
 <?php
 use Respect\Validation\Validator as DataValidator;
 
+/**
+ * @api {post} /user/edit-password Edit password of an user.
+ *
+ * @apiName edit-password
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path edit the password of a user.
+ *
+ * @apiPermission User
+ *
+ * @apiParam {string} newPassword the new password that the user wants to change.
+ *
+ * @apiParam {string} oldPassword the actual password of the user.
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 class EditPassword extends Controller {
     const PATH = '/edit-password';
     const METHOD = 'POST';
diff --git a/server/controllers/user/get-user.php b/server/controllers/user/get-user.php
index 6d257f7c..d59d22ee 100644
--- a/server/controllers/user/get-user.php
+++ b/server/controllers/user/get-user.php
@@ -2,6 +2,25 @@
 use Respect\Validation\Validator as DataValidator;
 DataValidator::with('CustomValidations', true);
 
+/**
+ * @api {post} /user/get-user Give back the information of an specific user.
+ *
+ * @apiName get-user
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path give back information about an specific user.
+ *
+ * @apiPermission Staff level 1
+ *
+ * @apiParam {string} userId The id of the user to find information of.
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 class GetUserByIdController extends Controller {
     const PATH = '/get-user';
     const METHOD = 'POST';
diff --git a/server/controllers/user/get-users.php b/server/controllers/user/get-users.php
index 8f3c6c7a..9d1d8b47 100644
--- a/server/controllers/user/get-users.php
+++ b/server/controllers/user/get-users.php
@@ -1,6 +1,31 @@
 <?php
 use Respect\Validation\Validator as DataValidator;
 
+/**
+ * @api {post} /user/get-users Give back the information of a list of users.
+ *
+ * @apiName get-users
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path give back information about a list of users.
+ *
+ * @apiPermission Staff level 1
+ *
+ * @apiParam {number} page number of pages of users.
+ *
+ * @apiParam {string} orderBy Parameter to order the users by tickets or id.
+ *
+ * @apiParam {bool} desc  Parameter to order the user ascending or descending way.
+ *
+ * @apiParam {string} search Key to find some specific users.
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 class GetUsersController extends Controller {
     const PATH = '/get-users';
     const METHOD = 'POST';
diff --git a/server/controllers/user/get.php b/server/controllers/user/get.php
index cbdf931d..aa9207b7 100644
--- a/server/controllers/user/get.php
+++ b/server/controllers/user/get.php
@@ -2,6 +2,23 @@
 use Respect\Validation\Validator as DataValidator;
 DataValidator::with('CustomValidations', true);
 
+/**
+ * @api {post} /user/get Give back the information of yourself.
+ *
+ * @apiName get
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path give back the information of a user.
+ *
+ * @apiPermission User
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 class GetUserController extends Controller {
     const PATH = '/get';
     const METHOD = 'POST';
diff --git a/server/controllers/user/list-ban.php b/server/controllers/user/list-ban.php
index 794f3ffd..c411d590 100644
--- a/server/controllers/user/list-ban.php
+++ b/server/controllers/user/list-ban.php
@@ -1,6 +1,21 @@
 <?php
 use Respect\Validation\Validator as DataValidator;
 
+/**
+ * @api {post} /user/list-ban Give back the list of banned users.
+ *
+ * @apiName list-ban
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path give back the list of banned users.
+ *
+ * @apiPermission Staff level 1
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 class ListBanUserController extends Controller {
     const PATH = '/list-ban';
     const METHOD = 'POST';
diff --git a/server/controllers/user/login.php b/server/controllers/user/login.php
index 99dc1b07..90b90969 100644
--- a/server/controllers/user/login.php
+++ b/server/controllers/user/login.php
@@ -1,5 +1,34 @@
 <?php
 
+/**
+ * @api {post} /user/login Login a user.
+ *
+ * @apiName login
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path login a user.
+ *
+ * @apiPermission Any
+ *
+ * @apiParam {bool} staff A bool that say if it want to login a staff or a normal user.
+ *
+ * @apiParam {string} email The email of the user to login.
+ *
+ * @apiParam {string} password The password of the user to login.
+ *
+ * @apiParam {bool} remember A bool that say if the session wants to be remembered.
+ *
+ * @apiParam {number} userId The id of the user to login.
+ *
+ * @apiParam {string} rememberToken Token to login automatically.
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 class LoginController extends Controller {
     const PATH = '/login';
     const METHOD = 'POST';
diff --git a/server/controllers/user/logout.php b/server/controllers/user/logout.php
index 5ba3b4a0..037b9598 100644
--- a/server/controllers/user/logout.php
+++ b/server/controllers/user/logout.php
@@ -1,4 +1,18 @@
 <?php
+/**
+ * @api {post} /user/logout log out the current user.
+ *
+ * @apiName log out 
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path log out the current user.
+ *
+ * @apiPermission Any
+ *
+ * @apiSuccess {Object} data
+ *
+ */
 class LogoutController extends Controller {
     const PATH = '/logout';
     const METHOD = 'POST';
diff --git a/server/controllers/user/recover-password.php b/server/controllers/user/recover-password.php
index 4aec4efe..9a9f7bd8 100644
--- a/server/controllers/user/recover-password.php
+++ b/server/controllers/user/recover-password.php
@@ -2,6 +2,29 @@
 use Respect\Validation\Validator as DataValidator;
 DataValidator::with('CustomValidations', true);
 
+/**
+ * @api {post} /user/recover-password change the password of the user using a token sended from the email
+ *
+ * @apiName recover password
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path change the password of the user usign a token sended from the email.
+ *
+ * @apiPermission Any
+ *
+ * @apiParam {string} email  the email of the user who forgot the password.
+ *
+ * @apiParam {string} password the new password of the user.
+ *
+ * @apiParam {string} token  the token that was sended to the email of the user.
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 class RecoverPasswordController extends Controller {
     const PATH = '/recover-password';
     const METHOD = 'POST';
diff --git a/server/controllers/user/send-recover-password.php b/server/controllers/user/send-recover-password.php
index 8852d68e..ef4dc4a8 100644
--- a/server/controllers/user/send-recover-password.php
+++ b/server/controllers/user/send-recover-password.php
@@ -2,6 +2,25 @@
 use Respect\Validation\Validator as DataValidator;
 DataValidator::with('CustomValidations', true);
 
+/**
+ * @api {post} /user/send-recover-password send a token to the email of the user to change his password
+ *
+ * @apiName send recover password
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path send a token to the email of the user to change his password
+ *
+ * @apiPermission Any
+ *
+ * @apiParam {string} email  the email of the user who forgot the password.
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 class SendRecoverPasswordController extends Controller {
     const PATH = '/send-recover-password';
     const METHOD = 'POST';
diff --git a/server/controllers/user/signup.php b/server/controllers/user/signup.php
index 41522832..d7d01723 100644
--- a/server/controllers/user/signup.php
+++ b/server/controllers/user/signup.php
@@ -3,6 +3,31 @@
 use Respect\Validation\Validator as DataValidator;
 DataValidator::with('CustomValidations', true);
 
+/**
+ * @api {post} /user/signup sign up a new user
+ *
+ * @apiName sign up
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path sign up a user on the system
+ *
+ * @apiPermission Any
+ *
+ * @apiParam {string} name  the name of the new user.
+ *
+ * @apiParam {string} email  the email of the new user.
+ *
+ * @apiParam {string} password  the password of the new user.
+ *
+ * @apiParam {string} apyKey  key to sign up  a user if the user system is disabled.
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 class SignUpController extends Controller {
     const PATH = '/signup';
     const METHOD = 'POST';
diff --git a/server/controllers/user/un-ban.php b/server/controllers/user/un-ban.php
index 5a451b88..07194080 100644
--- a/server/controllers/user/un-ban.php
+++ b/server/controllers/user/un-ban.php
@@ -1,6 +1,25 @@
 <?php
 use Respect\Validation\Validator as DataValidator;
 
+/**
+ * @api {post} /user/un-ban take a user out of banned list.
+ *
+ * @apiName un ban
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path take a user out of banned list.
+ *
+ * @apiPermission Staff level 1
+ *
+ * @apiParam {string} email  the email of the user who was banned.
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 class UnBanUserController extends Controller {
     const PATH = '/un-ban';
     const METHOD = 'POST';
diff --git a/server/controllers/user/verify.php b/server/controllers/user/verify.php
index c28e345f..4fd979ad 100644
--- a/server/controllers/user/verify.php
+++ b/server/controllers/user/verify.php
@@ -1,6 +1,27 @@
 <?php
 use Respect\Validation\Validator as DataValidator;
 
+/**
+ * @api {post} /user/verify verify the email of a new user.
+ *
+ * @apiName verify
+ *
+ * @apiGroup User
+ *
+ * @apiDescription This path verify the email of a new user.
+ *
+ * @apiPermission any
+ *
+ * @apiParam {string} email  the email of the user.
+ *
+ * @apiParam {string} token the key of validation the user.
+ *
+ * @apiError {String} message
+ *
+ * @apiSuccess {Object} data
+ *
+ */
+
 class VerifyController extends Controller{
     const PATH = '/verify';
     const METHOD = 'POST';