Merge pull request #835 from vmadman/master

Added Doc-Blocks for API documentation generation by ApiDoc

Author: Ilya Radchenko

.editorconfig

@@ -0,0 +1,20 @@
+# Strider Editor/IDE Settings
+# This file is used to promote consistent source code standards
+# amongst all Strider-CD contributors.
+# More information can be found here: http://editorconfig.org/
+
+# General Settings
+root = true
+
+# Settings for all files
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+# Settings specific to Markdown files
+[*.md]
+trim_trailing_whitespace = false

lib/routes/api/account.js

@@ -11,15 +11,18 @@ var Project = models.Project;
 
 router.use(auth.requireUserOr401);
 
-/**
- * @api {put} /:provider/:id Update a User's provider account 
- * @apiName UpdateAccount
- * @apiGroup Account
- *
- * @apiParam {String} provider Type of provider, e.g. github
- * @apiParam {Number} id Unique provider identification
- */
 router.route('/:provider/:id')
+
+  /**
+   * @api {put} /:provider/:id Update Provider Account
+   * @apiDescription Updates a provider account for the _active_ user (the API user).
+   * @apiName UpdateAccount
+   * @apiGroup Account
+   * @apiVersion 1.0.0
+   *
+   * @apiParam {String} provider Type of provider, e.g. github
+   * @apiParam {Number} id Unique provider identification
+   */
   .put(function (req, res) {
     var accounts = req.user.accounts;
     var provider = req.params.provider;
@@ -51,6 +54,17 @@ router.route('/:provider/:id')
       res.sendStatus(200);
     });
   })
+
+  /**
+   * @api {delete} /:provider/:id Delete Provider Account
+   * @apiDescription Deletes a provider account for the _active_ user (the API user).
+   * @apiName DeleteAccount
+   * @apiGroup Account
+   * @apiVersion 1.0.0
+   *
+   * @apiParam {String} provider Type of provider, e.g. github
+   * @apiParam {Number} id Unique provider identification
+   */
   .delete(function (req, res) {
     var accounts = req.user.accounts;
     var provider = req.params.provider;
@@ -94,14 +108,17 @@ router.route('/:provider/:id')
       });
   });
 
-/*
- * POST /api/account/password
- *
- * Change the password for this account.
- *
- * <password> - the new password for the account.
- */
 router.route('/password')
+
+  /**
+   * @api {post} /password Change Password
+   * @apiDescription Changes the password for the _active_ user (the API user).
+   * @apiName ChangePassword
+   * @apiGroup Account
+   * @apiVersion 1.0.0
+   *
+   * @apiParam (RequestBody) {String{6..}} password The new password, which must be at least 6 characters long.
+   */
   .post(function(req, res) {
     if (req.user !== undefined) {
       console.log('password change by ' + req.user.email);
@@ -133,14 +150,17 @@ router.route('/password')
   });
 
 
-/*
- * POST /api/account/email
- *
- * Change the email for this account.
- *
- * <email> - the new email for the account.
- */
  router.route('/email')
+
+ /**
+  * @api {post} /email Change Email
+  * @apiDescription Changes the email address for the _active_ user (the API user).
+  * @apiName ChangeEmail
+  * @apiGroup Account
+  * @apiVersion 1.0.0
+  *
+  * @apiParam (RequestBody) {String} email The new email address. This must be a VALID email address.
+  */
   .post(function(req, res) {
     var newEmail = req.body.email;
 

lib/routes/api/admin/index.js

@@ -10,8 +10,16 @@ var router = express.Router();
 
 router.use(auth.requireAdminOr401);
 
-/*
- * GET /admin/users
+/**
+ * @api {get} /admin/users Get All Users
+ * @apiPermission GlobalAdmin
+ * @apiDescription Retrieves a list of all Strider users.
+ * @apiName GetUsers
+ * @apiGroup Admin
+ * @apiVersion 1.0.0
+ *
+ * @apiExample {curl} CURL Example:
+ *    curl -X GET http://localhost/admin/users
  */
 router.route('/users')
   .get(function(req, res) {
@@ -29,23 +37,36 @@ router.route('/users')
     });
   });
 
-/*
- * GET /api/admin/jobs_status
- * Returns JSON object of last 100 jobs across entire system
+/**
+ * @apiIgnore
+ * @api {get} /admin/jobs Get Job Status
+ * @apiPermission GlobalAdmin
+ * @apiDescription Returns a JSON object of the last 100 jobs executed.
+ * @apiName GetJobs
+ * @apiGroup Admin
+ * @apiVersion 1.0.0
+ *
+ * @apiExample {curl} CURL Example:
+ *    curl -X GET http://localhost/admin/jobs
  */
 router.route('/jobs')
   .get(function(req, res) {
     res.send(500, 'Not yet implemented');
   });
 
-/*
- * POST /api/invite/new
- *
- * Create & email a new Strider invite. Only core@beyondfog.com may use this.
+/**
+ * @api {post} /invite/new Send Invite
+ * @apiPermission GlobalAdmin
+ * @apiDescription Create & email a new Strider invite.
+ * @apiName SendInvite
+ * @apiGroup Admin
+ * @apiVersion 1.0.0
  *
- * <invite_code> - Invite token string to set.
- * <email> - Email to send to.
+ * @apiExample {curl} CURL Example:
+ *    curl -X POST -d invite_code=xoxox -d email=new_guy@strider-cd.com http://localhost/invite/new
  *
+ * @apiParam (RequestBody) {String} invite_code The invite code/token to use in the invitation
+ * @apiParam (RequestBody) {String} email The email address of the new user being invited
  */
 router.route('/invite/new')
   .post(function (req, res) {
@@ -68,6 +89,20 @@ router.route('/invite/new')
     });
   });
 
+/**
+ * @api {post} /invite/revoke Revoke Invite
+ * @apiPermission GlobalAdmin
+ * @apiDescription Revokes a previously sent Strider invitation.
+ * @apiName RevokeInvite
+ * @apiGroup Admin
+ * @apiVersion 1.0.0
+ *
+ * @apiExample {curl} CURL Example:
+ *    curl -X POST -d invite_code=xoxox http://localhost/invite/revoke
+ *
+ * @apiParam (RequestBody) {String} invite_code The invite code/token of the invite
+ * being revoked.
+ */
 router.route('/invite/revoke')
   .post(function (req, res) {
     var inviteCode = requireBody('invite_code', req, res);

lib/routes/api/branches.js

@@ -1,18 +1,26 @@
 'use strict';
 
+
 var express = require('express');
 var Project = require('../../models').Project
 var middleware = require('../../middleware');
 var router = express.Router();
 var requireBody = middleware.requireBody;
 var root = router.route('/');
 
-  /*
-   * POST /:org/:repo/branches/
+  /**
+   * @api {post} /:org/:repo/branches Add Branch
+   * @apiUse ProjectReference
+   * @apiPermission ProjectAdmin
+   * @apiDescription Add a new branch for a project.
+   * @apiName AddBranch
+   * @apiGroup Branch
+   * @apiVersion 1.0.0
    *
-   * Add a new branch for a project. You must have admin privileges on the corresponding RepoConfig
-   * to be able to use this endpoint.
+   * @apiExample {curl} CURL Example:
+   *    curl -X POST -d name=newbranch http://localhost/api/strider/strider-cd/branches
    *
+   * @apiParam (RequestBody) {String} name The name of the new branch
    */
   root.post(requireBody(['name']), function (req, res) {
     req.project.addBranch(req.body.name, function (err, branch) {
@@ -21,11 +29,19 @@ var root = router.route('/');
     })
   });
 
-  /*
-   * PUT /:org/:repo/branches/
+  /**
+   * @api {put} /:org/:repo/branches Reorder Branches
+   * @apiUse ProjectReference
+   * @apiPermission ProjectAdmin
+   * @apiDescription Updates the branch order for a project.
+   * @apiName ReorderBranches
+   * @apiGroup Branch
+   * @apiVersion 1.0.0
    *
-   * Used to update the order of branches
+   * @apiExample {curl} CURL Example:
+   *    curl -X PUT -d branches=master,testing http://localhost/api/strider/strider-cd/branches
    *
+   * @apiParam (RequestBody) {String} branches The new branch order, comma delimited
    */
   root.put(requireBody(['branches']), function (req, res) {
     var branches = req.body.branches
@@ -39,11 +55,19 @@ var root = router.route('/');
     })
   });
 
-  /*
-   * DELETE /:org/:repo/branches/
+  /**
+   * @api {delete} /:org/:repo/branches Delete Branch
+   * @apiUse ProjectReference
+   * @apiPermission ProjectAdmin
+   * @apiDescription Deletes a branch from a project
+   * @apiName DeleteBranch
+   * @apiGroup Branch
+   * @apiVersion 1.0.0
    *
-   * Delete the specified branch from the project
+   * @apiExample {curl} CURL Example:
+   *    curl -X DELETE -d name=mybranch http://localhost/api/strider/strider-cd/branches
    *
+   * @apiParam (RequestBody) {String} name The name of the branch to delete
    */
   root.delete(requireBody(['name']), function (req, res) {
     var name = req.body.name

lib/routes/api/collaborators/index.js

@@ -15,12 +15,16 @@ module.exports = {
 }
 
 
-/*
- * GET /:org/:repo/collaborators
+/**
+ * @api {get} /:org/:repo/collaborators Get Collaborators
+ * @apiUse ProjectReference
+ * @apiDescription Gets a list of collaborators for a project
+ * @apiName GetCollaborators
+ * @apiGroup Collaborators
+ * @apiVersion 1.0.0
  *
- * Get the current list of collaborators for the Github repository.
- *
- * @param url Github html_url of the project.
+ * @apiExample {curl} CURL Example:
+ *    curl -X GET http://localhost/api/strider/strider-cd/collaborators
  */
 function get(req, res) {
   var project = req.params.org + '/' + req.params.repo;
@@ -45,15 +49,23 @@ function get(req, res) {
   });
 }
 
-/*
- * POST /:org/:repo/collaborators/
+/**
+ * @api {post} /:org/:repo/collaborators Add Collaborator
+ * @apiUse ProjectReference
+ * @apiPermission ProjectAdmin
+ * @apiDescription Add a new collaborator to a repository/project.
+ * @apiName AddCollaborator
+ * @apiGroup Collaborators
+ * @apiVersion 1.0.0
  *
- * Add a new collaborator for a Github repository. You must have admin privileges on the corresponding RepoConfig
- * to be able to use this endpoint.
+ * @apiExample {curl} CURL Example:
+ *    curl -X GET http://localhost/api/strider/strider-cd/collaborators?email=new_guy@strider-cd.com&access_level=2
  *
- * @param email Email address to add. If the user is not registered with Strider, we will send them an invite. If
- * they are already registered, they will receive a notification of access.
- * @param access_level Access level to grant. 0 = read-only, 2 = admin (default: 0)
+ * @apiParam (RequestBody) {String} email Email address to add. If the user is
+ * not registered with Strider, we will send them an invite. If they are already
+ * registered, they will receive a notification of access.
+ * @apiParam (RequestBody) {Number} access_level=0 Access level to grant to the
+ * new collaborator.  This can be `0`, for read only access, or `2` for admin access.
  */
 function post(req, res) {
   var project = req.params.org + '/' + req.params.repo
@@ -67,12 +79,19 @@ function post(req, res) {
   })
 }
 
-/*
- * DELETE /:org/:repo/collaborators/
+/**
+ * @api {delete} /:org/:repo/collaborators Delete Collaborator
+ * @apiUse ProjectReference
+ * @apiPermission ProjectAdmin
+ * @apiDescription Remove a collaborator from a repository/project.
+ * @apiName DeleteCollaborator
+ * @apiGroup Collaborators
+ * @apiVersion 1.0.0
  *
- * Delete the specified user from the list of collaborators for the Github repository.
+ * @apiExample {curl} CURL Example:
+ *    curl -X DELETE -d email=old_guy@strider-cd.com http://localhost/api/strider/strider-cd/collaborators
  *
- * @param email Email of the user.
+ * @apiParam (RequestBody) {String} email Email address to remove from the repo/project.
  */
 function del(req, res) {
   var project = req.params.org + '/' + req.params.repo

lib/routes/api/index.js

@@ -7,3 +7,36 @@ router.use('/account', require('./account'));
 router.use('/admin', require('./admin'));
 
 module.exports = router;
+
+
+// Globals & Commons for ApiDoc ..
+
+/**
+ * @apiDefine RequestUrl Request URL Parameters
+ *  Indicates that this parameter should be specified in the request URL.
+ */
+
+/**
+ * @apiDefine RequestBody Request Body Parameters
+ *  Indicates that this parameter should be specified in the request body.
+ */
+
+/**
+ * @apiDefine ProjectAdmin
+ *  You must have admin privileges on the corresponding RepoConfig to be able to use this endpoint.
+ */
+
+/**
+ * @apiDefine GlobalAdmin
+ *  You must have admin privileges in Strider (globally) in order to use this endpoint.
+ */
+
+/**
+ * @apiDefine ProjectReference
+ *
+ * @apiParam (RequestUrl) {String} org The organization name for the project.  This is
+ * usually a GitHub user or organization name (e.g. "strider" in "strider/strider-cd")
+ * but may vary from one project provider to another. (as another example,
+ * in GitLab this refers to the repository's "group").
+ * @apiParam (RequestUrl) {String} repo The project's repository name.
+ */