Add User REST API documentation

GladysAssistant · Dec 10, 2016 · b320d96 · b320d96
1 parent 8b60513
commit b320d96
Showing 1 changed file with 79 additions and 19 deletions.
diff --git a/api/controllers/UserController.js b/api/controllers/UserController.js
@@ -8,17 +8,42 @@
   */
 
 /**
- * UserController
- *
- * @description :: Server-side logic for managing users
- * @help        :: See http://links.sailsjs.org/docs/controllers
+ * @apiDefine UserSuccess
+ * @apiSuccess {String} firstname Firstname
+ * @apiSuccess {String} lastname  Lastname
+ * @apiSuccess {String} email  Email
+ * @apiSuccess {date} birthdate  Birthdate
+ * @apiSuccess {integer} gender  gender
+ * @apiSuccess {String} language  language of the user
+ * @apiSuccess {String} assistantName  The name of your assistant for you
+ * @apiSuccess {integer} preparationTimeAfterWakeUp  Time to prepare after wake up 
+ * @apiSuccess {String=admin, habitant, guest} role  The role of the user in the system
  */
 
+/**
+ * @apiDefine UserParam
+ * @apiSuccess {String} firstname Firstname
+ * @apiSuccess {String} lastname  Lastname
+ * @apiSuccess {String} email  Email
+ * @apiSuccess {date} birthdate  Birthdate
+ * @apiSuccess {integer} gender  gender
+ * @apiSuccess {String} language  language of the user
+ * @apiSuccess {String} password  A Password
+ * @apiSuccess {String} assistantName  The name of your assistant for you
+ * @apiSuccess {integer} preparationTimeAfterWakeUp  Time to prepare after wake up 
+ * @apiSuccess {String=admin, habitant, guest} role  The role of the user in the system
+ */
 module.exports = {
 
     /**
-     * Get all users
-     */
+   * @api {get} /user get all users
+   * @apiName getUsers
+   * @apiGroup User
+   * @apiPermission authenticated
+   * @apiPermission admin
+   * 
+   * @apiUse UserSuccess
+   */
    index: function(req, res, next){
       gladys.user.get()
         .then(function(users){
@@ -27,9 +52,17 @@ module.exports = {
         .catch(next);
    },
 
-   /**
-    * Create a user
-    */
+    /**
+   * @api {post} /user create a user
+   * @apiName createUser
+   * @apiGroup User
+   * @apiPermission authenticated
+   * @apiPermission admin
+   * 
+   * @apiUse UserParam
+   * 
+   * @apiUse UserSuccess
+   */
    create: function(req, res, next){
        gladys.user.create(req.body)
          .then(function(user){
@@ -39,8 +72,15 @@ module.exports = {
    },
 
    /**
-    * User login
-    */
+   * @api {post} /user/user Login
+   * @apiName LoginUser
+   * @apiGroup User
+   * 
+   * @apiParam {String} email Email
+   * @apiParam {String} password Password
+   * 
+   * @apiUse UserSuccess
+   */
    login: function(req, res, next){
        gladys.user.login(req.body)
          .then(function(user){
@@ -56,9 +96,16 @@ module.exports = {
          .catch(next);
    },
 
-   /**
-    * Update a user
-    */
+    /**
+   * @api {patch} /user/:id update a user
+   * @apiName updateUser
+   * @apiGroup User
+   * @apiPermission authenticated
+   * 
+   * @apiUse UserParam
+   * 
+   * @apiUse UserSuccess
+   */
    update: function(req, res, next){
        if(req.params.id != req.session.User.id){
           return res.forbidden('You cannot modify another user than you.');
@@ -78,8 +125,14 @@ module.exports = {
    },
 
    /**
-    * Delete a user
-    */
+   * @api {delete} /user/:id delete a user
+   * @apiName deleteUser
+   * @apiGroup User
+   * @apiPermission authenticated
+   * @apiPermission admin
+   * 
+   * @apiUse UserSuccess
+   */
    delete: function(req, res, next){
        gladys.user.delete({id: req.params.id})
          .then(function(user){
@@ -88,9 +141,16 @@ module.exports = {
          .catch(next);
    },
 
-/**
- * return the current connected user
- */
+  /**
+   * @api {get} /user/whoami WhoAmI
+   * @apiName WhoAmIUser
+   * @apiGroup User
+   * @apiPermission authenticated
+   * 
+   * @apiDescription Return currently connected user
+   * 
+   * @apiUse UserSuccess
+   */
   whoami: function(req, res, next){
     var user = {
       firstname: req.session.User.firstname,