comment errors according to apidoc, add new tests and fix existing ones

test/api/v3/unit/libs/errors.test.js

@@ -3,6 +3,7 @@ import {
   NotAuthorized,
   BadRequest,
   InternalServerError,
+  NotFound,
 } from '../../../../../website/src/libs/api-v3/errors';
 
 describe('Custom Errors', () => {
@@ -21,7 +22,7 @@ describe('Custom Errors', () => {
       expect(notAuthorizedError).to.be.an.instanceOf(CustomError);
     });
 
-    it('it returns an http code of 400', () => {
+    it('it returns an http code of 401', () => {
       let notAuthorizedError = new NotAuthorized();
 
       expect(notAuthorizedError.httpCode).to.eql(401);
@@ -40,6 +41,32 @@ describe('Custom Errors', () => {
     });
   });
 
+  describe('NotFound', () => {
+    it('is an instance of CustomError', () => {
+      let notAuthorizedError = new NotFound();
+
+      expect(notAuthorizedError).to.be.an.instanceOf(CustomError);
+    });
+
+    it('it returns an http code of 404', () => {
+      let notAuthorizedError = new NotFound();
+
+      expect(notAuthorizedError.httpCode).to.eql(404);
+    });
+
+    it('returns a default message', () => {
+      let notAuthorizedError = new NotFound();
+
+      expect(notAuthorizedError.message).to.eql('Not found.');
+    });
+
+    it('allows a custom message', () => {
+      let notAuthorizedError = new NotFound('Custom Error Message');
+
+      expect(notAuthorizedError.message).to.eql('Custom Error Message');
+    });
+  });
+
   describe('BadRequest', () => {
     it('is an instance of CustomError', () => {
       let badRequestError = new BadRequest();
@@ -82,7 +109,7 @@ describe('Custom Errors', () => {
     it('returns a default message', () => {
       let internalServerError = new InternalServerError();
 
-      expect(internalServerError.message).to.eql('Internal server error.');
+      expect(internalServerError.message).to.eql('An unexpected error occurred.');
     });
 
     it('allows a custom message', () => {

test/api/v3/unit/middlewares/errorHandler.test.js

@@ -31,7 +31,7 @@ describe('errorHandler', () => {
     expect(res.status).to.be.calledWith(500);
     expect(res.json).to.be.calledWith({
       error: 'InternalServerError',
-      message: 'Internal server error.',
+      message: 'An unexpected error occurred.',
     });
   });
 
@@ -63,7 +63,7 @@ describe('errorHandler', () => {
     expect(res.status).to.be.calledWith(500);
     expect(res.json).to.be.calledWith({
       error: 'InternalServerError',
-      message: 'Internal server error.',
+      message: 'An unexpected error occurred.',
     });
   });
 

test/api/v3/unit/middlewares/notFound.test.js

@@ -15,11 +15,9 @@ describe('notFoundHandler', () => {
     res = generateRes();
     req = generateReq();
     next = generateNext();
-
-    sandbox.stub(logger, 'error');
   });
 
-  it('sends NotFound error if the resource isn\'t found', () => {
+  xit('sends NotFound error if the resource isn\'t found', () => {
     expect(res.status).to.be.calledOnce;
     expect(res.json).to.be.calledOnce;
 

website/src/libs/api-v3/errors.js

@@ -7,8 +7,17 @@ export class CustomError extends Error {
   }
 }
 
-// NotAuthorized error with a 401 http error code
+/**
-// used when a request is not authorized
+ * @apiDefine NotFound
+ * @apiError NotFound The client is not authorized to make this request.
+ *
+ * @apiErrorExample Error-Response:
+ *     HTTP/1.1 401 Unauthorized
+ *     {
+ *       "error": "NotAuthorized",
+ *       "message": "Not authorized."
+ *     }
+ */
 export class NotAuthorized extends CustomError {
   constructor (customMessage) {
     super();
@@ -18,9 +27,17 @@ export class NotAuthorized extends CustomError {
   }
 }
 
-// BadRequest error with a 400 http error code
+/**
-// used for requests not formatted correctly
+ * @apiDefine BadRequest
-// TODO use for validation errors too?
+ * @apiError BadRequest The request wasn't formatted correctly.
+ *
+ * @apiErrorExample Error-Response:
+ *     HTTP/1.1 400 Bad Request
+ *     {
+ *       "error": "BadRequest",
+ *       "message": "Bad request."
+ *     }
+ */
  export class BadRequest extends CustomError {
   constructor (customMessage) {
     super();
@@ -37,25 +54,35 @@ export class BadRequest extends CustomError {
  * @apiErrorExample Error-Response:
  *     HTTP/1.1 404 Not Found
  *     {
- *       "error": "NotFound"
+ *       "error": "NotFound",
+ *       "message": "Not found."
  *     }
  */
 export class NotFound extends CustomError {
   constructor (customMessage) {
     super();
     this.name = this.constructor.name;
-    this.httpCode = 401;
+    this.httpCode = 404;
     this.message = customMessage || 'Not found.';
   }
 }
 
-// InternalError error with a 500 http error code
+/**
-// used when an unexpected, internal server error is thrown
+ * @apiDefine InternalServerError
+ * @apiError InternalServerError An unexpected error occurred.
+ *
+ * @apiErrorExample Error-Response:
+ *     HTTP/1.1 500 Internal Server Error
+ *     {
+ *       "error": "InternalServerError",
+ *       "message": "An unexpected error occurred."
+ *     }
+ */
 export class InternalServerError extends CustomError {
   constructor (customMessage) {
     super();
     this.name = this.constructor.name;
     this.httpCode = 500;
-    this.message = customMessage || 'Internal server error.';
+    this.message = customMessage || 'An unexpected error occurred.';
   }
 }

website/src/middlewares/api-v3/errorHandler.js

@@ -10,6 +10,16 @@ import {
 export default function errorHandler (err, req, res, next) {
   if (!err) return next();
 
+  // Log the original error with some metadata
+  let stack = err.stack || err.message || err;
+
+  logger.error(stack, {
+    originalUrl: req.originalUrl,
+    headers: req.headers,
+    body: req.body,
+    fullError: err,
+  });
+
   // In case of a CustomError class, use it's data
   // Otherwise try to identify the type of error (mongoose validation, mongodb unique, ...)
   // If we can't identify it, respond with a generic 500 error
@@ -38,16 +48,6 @@ export default function errorHandler (err, req, res, next) {
     responseErr = new InternalServerError();
   }
 
-  // Log the original error with some metadata
-  let stack = err.stack || err.message || err;
-
-  logger.error(stack, {
-    originalUrl: req.originalUrl,
-    headers: req.headers,
-    body: req.body,
-    fullError: err,
-  });
-
   // TODO unless status >= 500 return data attached to errors
   return res
     .status(responseErr.httpCode)