Add docs for brand, category, model, and item

stockpile-co · Mar 19, 2017 · 6d63c20 · 6d63c20
1 parent 9c736a7
commit 6d63c20
Show file tree

Hide file tree

Showing 4 changed files with 236 additions and 0 deletions.
diff --git a/controllers/brand.js b/controllers/brand.js
@@ -6,11 +6,66 @@ const brand = module.exports
 endpoint.addAllMethods(brand, 'brand', 'brandID')
 
 brand.mount = app => {
+  /**
+   * @apiDefine BrandResponse
+   *
+   * @apiExample {json} Response format:
+   * {
+   *   "brandID": 0,
+   *   "organizationID": 0,
+   *   "name": ""
+   * }
+   */
+
+  /**
+   * @api {get} /brand Get all brands
+   * @apiName GetBrands
+   * @apiGroup Brand
+   *
+   * @apiExample {json} Response format:
+   * {
+   *   results: [
+   *     {
+   *       "brandID": 0,
+   *       "organizationID": 0,
+   *       "name": ""
+   *     }
+   *   ]
+   * }
+   */
   app.get({name: 'get all brands', path: 'brand'}, auth.verify, brand.getAll)
+  /**
+   * @api {get} /brand/:brandID Get brand
+   * @apiName GetBrand
+   * @apiGroup Brand
+   *
+   * @apiUse BrandResponse
+   */
   app.get({name: 'get brand', path: 'brand/:brandID'}, auth.verify, brand.get)
+  /**
+   * @api {put} /brand Create a brand
+   * @apiName CreateBrand
+   * @apiGroup Brand
+   *
+   * @apiParam {String{0...255}} name Name of brand
+   */
   app.put({name: 'create brand', path: 'brand'}, auth.verify, brand.create)
+  /**
+   * @api {put} /brand/:brandID Update a brand
+   * @apiName UpdateBrand
+   * @apiGroup Brand
+   *
+   * @apiParam {String{0...255}} [name] Name of brand
+   *
+   * @apiUse BrandResponse
+   */
   app.put({name: 'update brand', path: 'brand/:brandID'},
           auth.verify, brand.update)
+  /**
+   * @api {delete} /brand/:brandID Delete a brand
+   * @apiName DeleteBrand
+   * @apiGroup Brand
+   */
   app.del({name: 'delete brand', path: 'brand/:brandID'},
           auth.verify, brand.delete)
 }
diff --git a/controllers/category.js b/controllers/category.js
@@ -6,14 +6,69 @@ const category = module.exports
 endpoint.addAllMethods(category, 'category', 'categoryID')
 
 category.mount = app => {
+  /**
+   * @apiDefine CategoryResponse
+   *
+   * @apiExample {json} Response format:
+   * {
+   *   "categoryID": 0,
+   *   "organizationID": 0,
+   *   "name": ""
+   * }
+   */
+
+  /**
+   * @api {get} /category Get all categories
+   * @apiName GetCategories
+   * @apiGroup Category
+   *
+   * @apiExample {json} Response format:
+   * {
+   *   results: [
+   *     {
+   *       "categoryID": 0,
+   *       "organizationID": 0,
+   *       "name": ""
+   *     }
+   *   ]
+   * }
+   */
   app.get({name: 'get all categories', path: 'category'},
           auth.verify, category.getAll)
+  /**
+   * @api {get} /category/:categoryID Get category
+   * @apiName GetCategory
+   * @apiGroup Category
+   *
+   * @apiUse CategoryResponse
+   */
   app.get({name: 'get category', path: 'category/:categoryID'},
           auth.verify, category.get)
+  /**
+   * @api {put} /category Create a category
+   * @apiName CreateCategory
+   * @apiGroup Category
+   *
+   * @apiParam {String{0...255}} name Name of category
+   */
   app.put({name: 'create category', path: 'category'},
           auth.verify, category.create)
+  /**
+   * @api {put} /category/:categoryID Update a category
+   * @apiName UpdateCategory
+   * @apiGroup Category
+   *
+   * @apiParam {String{0...255}} [name] Name of category
+   */
   app.put({name: 'update category', path: 'category/:categoryID'},
           auth.verify, category.update)
+  /**
+   * @api {delete} /category/:categoryID Delete a category
+   * @apiName DeleteCategory
+   * @apiGroup Category
+   *
+   * @apiUse CategoryResponse
+   */
   app.del({name: 'delete category', path: 'category/:categoryID'},
           auth.verify, category.delete)
 }
diff --git a/controllers/item.js b/controllers/item.js
@@ -41,9 +41,76 @@ item.getAll = endpoint.getAll('item', {modify: item.withFieldsAndFilters})
 item.get = endpoint.get('item', 'tag', {modify: item.withFieldsAndFilters})
 
 item.mount = app => {
+  /**
+   * @apiDefine ItemResponse
+   *
+   * @apiExample {json} Response format:
+   * {
+   *   "itemID": 0,
+   *   "organizationID": 0,
+   *   "modelID": 0,
+   *   "categoryID": 0,
+   *   "tag": "234234"
+   * }
+   */
+
+  /**
+   * @api {get} /item Get all items
+   * @apiName GetItems
+   * @apiGroup Item
+   *
+   * @apiParam {Number} [brandID] Return items with only this brandID
+   * @apiParam {Number} [modelID] Return items with only this modelID
+   * @apiParam {Number} [categoryID] Return items with only this categoryID
+   *
+   * @apiExample {json} Response format:
+   * {
+   *   results: [
+   *     {
+   *       "itemID": 0,
+   *       "organizationID": 0,
+   *       "modelID": 0,
+   *       "categoryID": 0,
+   *       "tag": "234234"
+   *     }
+   *   ]
+   * }
+   */
   app.get({name: 'get all items', path: 'item'}, auth.verify, item.getAll)
+  /**
+   * @api {get} /item/:tag Get an item
+   * @apiName GetItem
+   * @apiGroup Item
+   *
+   * @apiUse ItemResponse
+   */
   app.get({name: 'get item', path: 'item/:tag'}, auth.verify, item.get)
+  /**
+   * @api {put} /item Create an item
+   * @apiName CreateItem
+   * @apiGroup Item
+   *
+   * @apiParam {Number} [modelID] ID of model
+   * @apiParam {Number} [categoryID] ID of category
+   * @apiParam {String} tag Unique identifier of item
+   */
   app.put({name: 'create item', path: 'item'}, auth.verify, item.create)
+  /**
+   * @api {put} /item/:tag Update item
+   * @apiName UpdateItem
+   * @apiGroup Item
+   *
+   * @apiParam {Number} [modelID] ID of model
+   * @apiParam {Number} [categoryID] ID of category
+   * @apiParam {String} [tag] Unique identifier of item
+   *
+   * @apiUse ItemResponse
+   */
   app.put({name: 'update item', path: 'item/:tag'}, auth.verify, item.update)
+  /**
+   * @api {delete} /item/:tag Delete item
+   * @apiName DeleteItem
+   * @apiGroup Item
+   */
   app.del({name: 'delete item', path: 'item/:tag'}, auth.verify, item.delete)
 }
diff --git a/controllers/model.js b/controllers/model.js
@@ -6,11 +6,70 @@ const model = module.exports
 endpoint.addAllMethods(model, 'model', 'modelID')
 
 model.mount = app => {
+  /**
+   * @apiDefine ModelResponse
+   *
+   * @apiExample {json} Response format:
+   * {
+   *   "modelID": 0,
+   *   "brandID": 0,
+   *   "organizationID": 0,
+   *   "name": ""
+   * }
+   */
+
+  /**
+   * @api {get} /model Get all models
+   * @apiName GetModels
+   * @apiGroup Model
+   *
+   * @apiExample {json} Response format:
+   * {
+   *   results: [
+   *     {
+   *       "modelID": 0,
+   *       "brandID": 0,
+   *       "organizationID": 0,
+   *       "name": ""
+   *     }
+   *   ]
+   * }
+   */
   app.get({name: 'get all models', path: 'model'}, auth.verify, model.getAll)
+  /**
+   * @api {get} /model/:modelID Get model
+   * @apiName GetModel
+   * @apiGroup Model
+   *
+   * @apiUse ModelResponse
+   */
   app.get({name: 'get model', path: 'model/:modelID'}, auth.verify, model.get)
+  /**
+   * @api {put} /model Create a model
+   * @apiName CreateModel
+   * @apiGroup Model
+   *
+   * @apiParam {String{0...255}} name Name of model
+   * @apiParam {Number} brandID ID of a brand
+   */
   app.put({name: 'create model', path: 'model'}, auth.verify, model.create)
+  /**
+   * @api {put} /model/:modelID Update a model
+   * @apiName UpdateModel
+   * @apiGroup Model
+   *
+   * @apiParam {String{0...255}} [name] Name of model
+   * @apiParam {Number} [brandID] ID of a brand
+   *
+   * @apiUse ModelResponse
+   */
   app.put({name: 'update model', path: 'model/:modelID'},
           auth.verify, model.update)
+  /**
+   * @api {delete} /model/:modelID Delete a model
+   * @apiName DeleteModel
+   * @apiGroup Model
+   */
   app.del({name: 'delete model', path: 'model/:modelID'},
           auth.verify, model.delete)
 }