feat(docs): add apidoc support

42Zavattas · May 2, 2015 · 173e1e4 · 173e1e4
1 parent 9780043
commit 173e1e4
Show file tree

Hide file tree

Showing 11 changed files with 259 additions and 38 deletions.
diff --git a/api/index.js b/api/index.js
@@ -20,15 +20,16 @@ var BangularGenerator = yeoman.generators.NamedBase.extend({
     this.objectName = _.capitalize(_.camelize(this.name));
     this.objectsName = this.objectName + 's';
 
+    var filters = this.config.get('filters');
+    this.filters = filters || {};
+
     var prompts = [{
       type: 'input',
       name: 'url',
       message: 'On which url do you want to attach the ' + chalk.red(this.objectName) + ' endpoint? ',
       default: '/api/' + this.routeName
     }];
 
-    var filters = this.config.get('filters');
-
     if (filters && filters.ngResource) {
       prompts.push({
         type: 'confirm',

diff --git a/api/templates/json/controller.js b/api/templates/json/controller.js
@@ -6,55 +6,95 @@ function handleError (res, err) {
   return res.status(500).send(err);
 }
 
+<% if (!filters.apidoc) { %>
 /**
- * Get list of <%= objectsName %>s
+ * Get list of <%= objectName %>
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {get} /<%= instancesName %> Get a list of <%= instancesName %>
+ * @apiVersion 0.1.0
+ * @apiName Get<%= objectsName %>
+ * @apiGroup <%= objectsName %>
+ *
+ */<% } %>
 exports.index = function (req, res) {
   fs.readFile('server/api/<%= fileName %>/<%= fileName %>.data.json', 'utf-8', function (err, <%= instancesName %>) {
     if (err) { return handleError(res, err); }
     res.status(200).json(JSON.parse(<%= instancesName %>));
   });
 };
 
+<% if (!filters.apidoc) { %>
 /**
  * Get a single <%= objectName %>
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {get} /<%= instancesName %>/:id Get a single <%= instanceName %>
+ * @apiVersion 0.1.0
+ * @apiName Get<%= objectName %>
+ * @apiGroup <%= objectsName %>
+ *
+ */<% } %>
 exports.show = function (req, res) {
   res.status(200).json({});
 };
 
+<% if (!filters.apidoc) { %>
 /**
- * Creates a new <%= objectName %>
+ * Creates a new <%= objectName %> in the DB.
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {post} /<%= instancesName %> Create a new <%= instanceName %>
+ * @apiVersion 0.1.0
+ * @apiName Create<%= objectName %>
+ * @apiGroup <%= objectsName %>
+ *
+ */<% } %>
 exports.create = function (req, res) {
   res.status(201).json({});
 };
 
+<% if (!filters.apidoc) { %>
 /**
- * Updates an existing <%= objectName %>
+ * Updates an existing <%= objectName %> in the DB.
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {put} /<%= instancesName %>/:id Updates an existing <%= instanceName %>
+ * @apiVersion 0.1.0
+ * @apiName Update<%= objectName %>
+ * @apiGroup <%= objectsName %>
+ *
+ */<% } %>
 exports.update = function (req, res) {
   res.status(200).json({});
 };
 
+<% if (!filters.apidoc) { %>
 /**
- * Deletes a <%= objectName %>
+ * Deletes a <%= objectName %> from the DB.
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {delete} /<%= instancesName %>/:id Deletes a <%= instanceName %>
+ * @apiVersion 0.1.0
+ * @apiName Remove<%= objectName %>
+ * @apiGroup <%= objectsName %>
+ *
+ */<% } %>
 exports.destroy = function (req, res) {
   return res.status(204);
 };
diff --git a/api/templates/mongo/controller.js b/api/templates/mongo/controller.js
@@ -6,53 +6,89 @@ var <%= objectName %> = require('./<%= fileName %>.model');
 function handleError (res, err) {
   return res.status(500).send(err);
 }
-
+<% if (!filters.apidoc) { %>
 /**
  * Get list of <%= objectName %>
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {get} /<%= instancesName %> Get a list of <%= instancesName %>
+ * @apiVersion 0.1.0
+ * @apiName Get<%= objectsName %>
+ * @apiDescription Get all the <%= instanceName %>.
+ * @apiGroup <%= objectsName %>
+ *
+ */<% } %>
 exports.index = function (req, res) {
   <%= objectName %>.find(function (err, <%= instancesName %>) {
     if (err) { return handleError(res, err); }
     return res.status(200).json(<%= instancesName %>);
   });
 };
-
+<% if (!filters.apidoc) { %>
 /**
  * Get a single <%= objectName %>
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {get} /<%= instancesName %>/:id Get a single <%= instanceName %>
+ * @apiVersion 0.1.0
+ * @apiName Get<%= objectName %>
+ * @apiDescription Get only one unique element of <%= instanceName %> based on its unique id.
+ * @apiGroup <%= objectsName %>
+ *
+ * @apiParam {String} id <%= objectsName %> unique id.
+ *
+ */<% } %>
 exports.show = function (req, res) {
   <%= objectName %>.findById(req.params.id, function (err, <%= instanceName %>) {
     if (err) { return handleError(res, err); }
     if (!<%= instanceName %>) { return res.status(404).end(); }
     return res.status(200).json(<%= instanceName %>);
   });
 };
-
+<% if (!filters.apidoc) { %>
 /**
  * Creates a new <%= objectName %> in the DB.
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {post} /<%= instancesName %> Create a new <%= instanceName %>
+ * @apiVersion 0.1.0
+ * @apiName Create<%= objectName %>
+ * @apiDescription Creates a new <%= instanceName %>.
+ * @apiGroup <%= objectsName %>
+ *
+ */<% } %>
 exports.create = function (req, res) {
   <%= objectName %>.create(req.body, function (err, <%= instanceName %>) {
     if (err) { return handleError(res, err); }
     return res.status(201).json(<%= instanceName %>);
   });
 };
-
+<% if (!filters.apidoc) { %>
 /**
  * Updates an existing <%= objectName %> in the DB.
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {put} /<%= instancesName %>/:id Updates an existing <%= instanceName %>
+ * @apiVersion 0.1.0
+ * @apiName Update<%= objectName %>
+ * @apiDescription Update an element of <%= instanceName %> based on its unique id.
+ * @apiGroup <%= objectsName %>
+ *
+ * @apiParam {String} id <%= objectsName %> unique id.
+ *
+ */<% } %>
 exports.update = function (req, res) {
   if (req.body._id) { delete req.body._id; }
   <%= objectName %>.findById(req.params.id, function (err, <%= instanceName %>) {
@@ -65,13 +101,23 @@ exports.update = function (req, res) {
     });
   });
 };
-
+<% if (!filters.apidoc) { %>
 /**
  * Deletes a <%= objectName %> from the DB.
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {delete} /<%= instancesName %>/:id Deletes a <%= instanceName %>
+ * @apiVersion 0.1.0
+ * @apiName Remove<%= objectName %>
+ * @apiDescription Delete an element of <%= instanceName %> based on its unique id.
+ * @apiGroup <%= objectsName %>
+ *
+ * @apiParam {String} id <%= objectsName %> unique id.
+ *
+ */<% } %>
 exports.destroy = function (req, res) {
   <%= objectName %>.findById(req.params.id, function (err, <%= instanceName %>) {
     if (err) { return handleError(res, err); }

diff --git a/api/templates/restock/controller.js b/api/templates/restock/controller.js
@@ -8,58 +8,98 @@ function handleError (res, err) {
 
 var apiUrl = 'http://www.restock.io/api/';
 
+<% if (!filters.apidoc) { %>
 /**
- * Get list of <%= objectsName %>
+ * Get list of <%= objectName %>
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {get} /<%= instancesName %> Get a list of <%= instancesName %>
+ * @apiVersion 0.1.0
+ * @apiName Get<%= objectsName %>
+ * @apiGroup <%= objectsName %>
+ *
+ */<% } %>
 exports.index = function (req, res) {
   request(apiUrl + '10{name:s}', function (err, resp, body) {
     if (err) { return handleError(res, err); }
     res.status(resp.statusCode).send(body);
   });
 };
 
+<% if (!filters.apidoc) { %>
 /**
  * Get a single <%= objectName %>
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {get} /<%= instancesName %>/:id Get a single <%= instanceName %>
+ * @apiVersion 0.1.0
+ * @apiName Get<%= objectName %>
+ * @apiGroup <%= objectsName %>
+ *
+ */<% } %>
 exports.show = function (req, res) {
   request(apiUrl + '{name:s}', function (err, resp, body) {
     if (err) { return handleError(res, err); }
     res.status(resp.statusCode).send(body);
   });
 };
 
+<% if (!filters.apidoc) { %>
 /**
- * Creates a new <%= objectName %>
+ * Creates a new <%= objectName %> in the DB.
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {post} /<%= instancesName %> Create a new <%= instanceName %>
+ * @apiVersion 0.1.0
+ * @apiName Create<%= objectName %>
+ * @apiGroup <%= objectsName %>
+ *
+ */<% } %>
 exports.create = function (req, res) {
   res.status(201).json({});
 };
 
+<% if (!filters.apidoc) { %>
 /**
- * Updates an existing <%= objectName %>
+ * Updates an existing <%= objectName %> in the DB.
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {put} /<%= instancesName %>/:id Updates an existing <%= instanceName %>
+ * @apiVersion 0.1.0
+ * @apiName Update<%= objectName %>
+ * @apiGroup <%= objectsName %>
+ *
+ */<% } %>
 exports.update = function (req, res) {
   res.status(200).json({});
 };
 
+<% if (!filters.apidoc) { %>
 /**
- * Deletes a <%= objectName %>
+ * Deletes a <%= objectName %> from the DB.
  *
  * @param req
  * @param res
- */
+ */<% } else { %>
+/**
+ * @api {delete} /<%= instancesName %>/:id Deletes a <%= instanceName %>
+ * @apiVersion 0.1.0
+ * @apiName Remove<%= objectName %>
+ * @apiGroup <%= objectsName %>
+ *
+ */<% } %>
 exports.destroy = function (req, res) {
   return res.status(204);
 };
diff --git a/app/index.js b/app/index.js
@@ -87,6 +87,10 @@ var BangularGenerator = yeoman.generators.Base.extend({
         value: 'sassdoc',
         name: 'SassDoc',
         checked: false
+      }, {
+        value: 'apidoc',
+        name: 'ApiDoc',
+        checked: false
       }]
     }, {
       type: 'checkbox',
@@ -143,13 +147,12 @@ var BangularGenerator = yeoman.generators.Base.extend({
       }
 
       if (props.docs && props.docs.length) {
+        self.filters.hasDocs = true;
         props.docs.forEach(function (doc) {
           self.filters[doc] = true;
         });
       }
 
-      self.filters.hasDocs = !!self.filters.sassdoc;
-
       if (props.tests && props.tests.length) {
         props.tests.forEach(function (test) {
           self.filters[test] = true;

diff --git a/app/templates/gulpfile.js b/app/templates/gulpfile.js
@@ -18,4 +18,5 @@ gulp.task('control',                  require('./tasks/control'));<% } if (filte
 gulp.task('e2e:update',               require('./tasks/test').e2eUpdate);
 gulp.task('e2e',        ['serve'],    require('./tasks/test').e2eTests);<% } if (filters.karma || filters.mocha) { %>
 gulp.task('test',                     require('./tasks/test').test);<% } if (filters.sassdoc) { %>
-gulp.task('sassdoc',                  require('./tasks/doc').sassdoc);<% } %>
+gulp.task('sassdoc',                  require('./tasks/doc').sassdoc);<% } if (filters.apidoc) { %>
+gulp.task('apidoc',                   require('./tasks/doc').apidoc);<% } %>