Skip to content

Commit bc36b9b

Browse files
balthazarbalthazar
committed
feat(docs): add apidoc support
Closes #14.
1 parent 9780043 commit bc36b9b

File tree

11 files changed

+259
-39
lines changed

11 files changed

+259
-39
lines changed

‎api/index.js

+3-2
Original file line numberDiff line numberDiff line change
@@ -20,15 +20,16 @@ var BangularGenerator = yeoman.generators.NamedBase.extend({
2020
this.objectName = _.capitalize(_.camelize(this.name));
2121
this.objectsName = this.objectName + 's';
2222

23+
var filters = this.config.get('filters');
24+
this.filters = filters || {};
25+
2326
var prompts = [{
2427
type: 'input',
2528
name: 'url',
2629
message: 'On which url do you want to attach the ' + chalk.red(this.objectName) + ' endpoint? ',
2730
default: '/api/' + this.routeName
2831
}];
2932

30-
var filters = this.config.get('filters');
31-
3233
if (filters && filters.ngResource) {
3334
prompts.push({
3435
type: 'confirm',

‎api/templates/json/controller.js

+49-9
Original file line numberDiff line numberDiff line change
@@ -6,55 +6,95 @@ function handleError (res, err) {
66
return res.status(500).send(err);
77
}
88

9+
<% if (!filters.apidoc) { %>
910
/**
10-
* Get list of <%= objectsName %>s
11+
* Get list of <%= objectName %>
1112
*
1213
* @param req
1314
* @param res
14-
*/
15+
*/<% } else { %>
16+
/**
17+
* @api {get} /<%= instancesName %> Get a list of <%= instancesName %>
18+
* @apiVersion 0.1.0
19+
* @apiName Get<%= objectsName %>
20+
* @apiGroup <%= objectsName %>
21+
*
22+
*/<% } %>
1523
exports.index = function (req, res) {
1624
fs.readFile('server/api/<%= fileName %>/<%= fileName %>.data.json', 'utf-8', function (err, <%= instancesName %>) {
1725
if (err) { return handleError(res, err); }
1826
res.status(200).json(JSON.parse(<%= instancesName %>));
1927
});
2028
};
2129

30+
<% if (!filters.apidoc) { %>
2231
/**
2332
* Get a single <%= objectName %>
2433
*
2534
* @param req
2635
* @param res
27-
*/
36+
*/<% } else { %>
37+
/**
38+
* @api {get} /<%= instancesName %>/:id Get a single <%= instanceName %>
39+
* @apiVersion 0.1.0
40+
* @apiName Get<%= objectName %>
41+
* @apiGroup <%= objectsName %>
42+
*
43+
*/<% } %>
2844
exports.show = function (req, res) {
2945
res.status(200).json({});
3046
};
3147

48+
<% if (!filters.apidoc) { %>
3249
/**
33-
* Creates a new <%= objectName %>
50+
* Creates a new <%= objectName %> in the DB.
3451
*
3552
* @param req
3653
* @param res
37-
*/
54+
*/<% } else { %>
55+
/**
56+
* @api {post} /<%= instancesName %> Create a new <%= instanceName %>
57+
* @apiVersion 0.1.0
58+
* @apiName Create<%= objectName %>
59+
* @apiGroup <%= objectsName %>
60+
*
61+
*/<% } %>
3862
exports.create = function (req, res) {
3963
res.status(201).json({});
4064
};
4165

66+
<% if (!filters.apidoc) { %>
4267
/**
43-
* Updates an existing <%= objectName %>
68+
* Updates an existing <%= objectName %> in the DB.
4469
*
4570
* @param req
4671
* @param res
47-
*/
72+
*/<% } else { %>
73+
/**
74+
* @api {put} /<%= instancesName %>/:id Updates an existing <%= instanceName %>
75+
* @apiVersion 0.1.0
76+
* @apiName Update<%= objectName %>
77+
* @apiGroup <%= objectsName %>
78+
*
79+
*/<% } %>
4880
exports.update = function (req, res) {
4981
res.status(200).json({});
5082
};
5183

84+
<% if (!filters.apidoc) { %>
5285
/**
53-
* Deletes a <%= objectName %>
86+
* Deletes a <%= objectName %> from the DB.
5487
*
5588
* @param req
5689
* @param res
57-
*/
90+
*/<% } else { %>
91+
/**
92+
* @api {delete} /<%= instancesName %>/:id Deletes a <%= instanceName %>
93+
* @apiVersion 0.1.0
94+
* @apiName Remove<%= objectName %>
95+
* @apiGroup <%= objectsName %>
96+
*
97+
*/<% } %>
5898
exports.destroy = function (req, res) {
5999
return res.status(204);
60100
};

‎api/templates/mongo/controller.js

+56-10
Original file line numberDiff line numberDiff line change
@@ -6,53 +6,89 @@ var <%= objectName %> = require('./<%= fileName %>.model');
66
function handleError (res, err) {
77
return res.status(500).send(err);
88
}
9-
9+
<% if (!filters.apidoc) { %>
1010
/**
1111
* Get list of <%= objectName %>
1212
*
1313
* @param req
1414
* @param res
15-
*/
15+
*/<% } else { %>
16+
/**
17+
* @api {get} /<%= instancesName %> Get a list of <%= instancesName %>
18+
* @apiVersion 0.1.0
19+
* @apiName Get<%= objectsName %>
20+
* @apiDescription Get all the <%= instanceName %>.
21+
* @apiGroup <%= objectsName %>
22+
*
23+
*/<% } %>
1624
exports.index = function (req, res) {
1725
<%= objectName %>.find(function (err, <%= instancesName %>) {
1826
if (err) { return handleError(res, err); }
1927
return res.status(200).json(<%= instancesName %>);
2028
});
2129
};
22-
30+
<% if (!filters.apidoc) { %>
2331
/**
2432
* Get a single <%= objectName %>
2533
*
2634
* @param req
2735
* @param res
28-
*/
36+
*/<% } else { %>
37+
/**
38+
* @api {get} /<%= instancesName %>/:id Get a single <%= instanceName %>
39+
* @apiVersion 0.1.0
40+
* @apiName Get<%= objectName %>
41+
* @apiDescription Get only one unique element of <%= instanceName %> based on its unique id.
42+
* @apiGroup <%= objectsName %>
43+
*
44+
* @apiParam {String} id <%= objectsName %> unique id.
45+
*
46+
*/<% } %>
2947
exports.show = function (req, res) {
3048
<%= objectName %>.findById(req.params.id, function (err, <%= instanceName %>) {
3149
if (err) { return handleError(res, err); }
3250
if (!<%= instanceName %>) { return res.status(404).end(); }
3351
return res.status(200).json(<%= instanceName %>);
3452
});
3553
};
36-
54+
<% if (!filters.apidoc) { %>
3755
/**
3856
* Creates a new <%= objectName %> in the DB.
3957
*
4058
* @param req
4159
* @param res
42-
*/
60+
*/<% } else { %>
61+
/**
62+
* @api {post} /<%= instancesName %> Create a new <%= instanceName %>
63+
* @apiVersion 0.1.0
64+
* @apiName Create<%= objectName %>
65+
* @apiDescription Creates a new <%= instanceName %>.
66+
* @apiGroup <%= objectsName %>
67+
*
68+
*/<% } %>
4369
exports.create = function (req, res) {
4470
<%= objectName %>.create(req.body, function (err, <%= instanceName %>) {
4571
if (err) { return handleError(res, err); }
4672
return res.status(201).json(<%= instanceName %>);
4773
});
4874
};
49-
75+
<% if (!filters.apidoc) { %>
5076
/**
5177
* Updates an existing <%= objectName %> in the DB.
5278
*
5379
* @param req
5480
* @param res
55-
*/
81+
*/<% } else { %>
82+
/**
83+
* @api {put} /<%= instancesName %>/:id Updates an existing <%= instanceName %>
84+
* @apiVersion 0.1.0
85+
* @apiName Update<%= objectName %>
86+
* @apiDescription Update an element of <%= instanceName %> based on its unique id.
87+
* @apiGroup <%= objectsName %>
88+
*
89+
* @apiParam {String} id <%= objectsName %> unique id.
90+
*
91+
*/<% } %>
5692
exports.update = function (req, res) {
5793
if (req.body._id) { delete req.body._id; }
5894
<%= objectName %>.findById(req.params.id, function (err, <%= instanceName %>) {
@@ -65,13 +101,23 @@ exports.update = function (req, res) {
65101
});
66102
});
67103
};
68-
104+
<% if (!filters.apidoc) { %>
69105
/**
70106
* Deletes a <%= objectName %> from the DB.
71107
*
72108
* @param req
73109
* @param res
74-
*/
110+
*/<% } else { %>
111+
/**
112+
* @api {delete} /<%= instancesName %>/:id Deletes a <%= instanceName %>
113+
* @apiVersion 0.1.0
114+
* @apiName Remove<%= objectName %>
115+
* @apiDescription Delete an element of <%= instanceName %> based on its unique id.
116+
* @apiGroup <%= objectsName %>
117+
*
118+
* @apiParam {String} id <%= objectsName %> unique id.
119+
*
120+
*/<% } %>
75121
exports.destroy = function (req, res) {
76122
<%= objectName %>.findById(req.params.id, function (err, <%= instanceName %>) {
77123
if (err) { return handleError(res, err); }

‎api/templates/restock/controller.js

+49-9
Original file line numberDiff line numberDiff line change
@@ -8,58 +8,98 @@ function handleError (res, err) {
88

99
var apiUrl = 'http://www.restock.io/api/';
1010

11+
<% if (!filters.apidoc) { %>
1112
/**
12-
* Get list of <%= objectsName %>
13+
* Get list of <%= objectName %>
1314
*
1415
* @param req
1516
* @param res
16-
*/
17+
*/<% } else { %>
18+
/**
19+
* @api {get} /<%= instancesName %> Get a list of <%= instancesName %>
20+
* @apiVersion 0.1.0
21+
* @apiName Get<%= objectsName %>
22+
* @apiGroup <%= objectsName %>
23+
*
24+
*/<% } %>
1725
exports.index = function (req, res) {
1826
request(apiUrl + '10{name:s}', function (err, resp, body) {
1927
if (err) { return handleError(res, err); }
2028
res.status(resp.statusCode).send(body);
2129
});
2230
};
2331

32+
<% if (!filters.apidoc) { %>
2433
/**
2534
* Get a single <%= objectName %>
2635
*
2736
* @param req
2837
* @param res
29-
*/
38+
*/<% } else { %>
39+
/**
40+
* @api {get} /<%= instancesName %>/:id Get a single <%= instanceName %>
41+
* @apiVersion 0.1.0
42+
* @apiName Get<%= objectName %>
43+
* @apiGroup <%= objectsName %>
44+
*
45+
*/<% } %>
3046
exports.show = function (req, res) {
3147
request(apiUrl + '{name:s}', function (err, resp, body) {
3248
if (err) { return handleError(res, err); }
3349
res.status(resp.statusCode).send(body);
3450
});
3551
};
3652

53+
<% if (!filters.apidoc) { %>
3754
/**
38-
* Creates a new <%= objectName %>
55+
* Creates a new <%= objectName %> in the DB.
3956
*
4057
* @param req
4158
* @param res
42-
*/
59+
*/<% } else { %>
60+
/**
61+
* @api {post} /<%= instancesName %> Create a new <%= instanceName %>
62+
* @apiVersion 0.1.0
63+
* @apiName Create<%= objectName %>
64+
* @apiGroup <%= objectsName %>
65+
*
66+
*/<% } %>
4367
exports.create = function (req, res) {
4468
res.status(201).json({});
4569
};
4670

71+
<% if (!filters.apidoc) { %>
4772
/**
48-
* Updates an existing <%= objectName %>
73+
* Updates an existing <%= objectName %> in the DB.
4974
*
5075
* @param req
5176
* @param res
52-
*/
77+
*/<% } else { %>
78+
/**
79+
* @api {put} /<%= instancesName %>/:id Updates an existing <%= instanceName %>
80+
* @apiVersion 0.1.0
81+
* @apiName Update<%= objectName %>
82+
* @apiGroup <%= objectsName %>
83+
*
84+
*/<% } %>
5385
exports.update = function (req, res) {
5486
res.status(200).json({});
5587
};
5688

89+
<% if (!filters.apidoc) { %>
5790
/**
58-
* Deletes a <%= objectName %>
91+
* Deletes a <%= objectName %> from the DB.
5992
*
6093
* @param req
6194
* @param res
62-
*/
95+
*/<% } else { %>
96+
/**
97+
* @api {delete} /<%= instancesName %>/:id Deletes a <%= instanceName %>
98+
* @apiVersion 0.1.0
99+
* @apiName Remove<%= objectName %>
100+
* @apiGroup <%= objectsName %>
101+
*
102+
*/<% } %>
63103
exports.destroy = function (req, res) {
64104
return res.status(204);
65105
};

‎app/index.js

+5-2
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,10 @@ var BangularGenerator = yeoman.generators.Base.extend({
8787
value: 'sassdoc',
8888
name: 'SassDoc',
8989
checked: false
90+
}, {
91+
value: 'apidoc',
92+
name: 'ApiDoc',
93+
checked: false
9094
}]
9195
}, {
9296
type: 'checkbox',
@@ -143,13 +147,12 @@ var BangularGenerator = yeoman.generators.Base.extend({
143147
}
144148

145149
if (props.docs && props.docs.length) {
150+
self.filters.hasDocs = true;
146151
props.docs.forEach(function (doc) {
147152
self.filters[doc] = true;
148153
});
149154
}
150155

151-
self.filters.hasDocs = !!self.filters.sassdoc;
152-
153156
if (props.tests && props.tests.length) {
154157
props.tests.forEach(function (test) {
155158
self.filters[test] = true;

‎app/templates/gulpfile.js

+2-1
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,5 @@ gulp.task('control', require('./tasks/control'));<% } if (filte
1818
gulp.task('e2e:update', require('./tasks/test').e2eUpdate);
1919
gulp.task('e2e', ['serve'], require('./tasks/test').e2eTests);<% } if (filters.karma || filters.mocha) { %>
2020
gulp.task('test', require('./tasks/test').test);<% } if (filters.sassdoc) { %>
21-
gulp.task('sassdoc', require('./tasks/doc').sassdoc);<% } %>
21+
gulp.task('sassdoc', require('./tasks/doc').sassdoc);<% } if (filters.apidoc) { %>
22+
gulp.task('apidoc', require('./tasks/doc').apidoc);<% } %>

0 commit comments

Comments
 (0)