Swagger Error and Note Support

lib/exports-helper.js

@@ -12,7 +12,7 @@ var debug = require('debug')('strong-remoting:exports-helper');
 /*!
  * Constants
  */
-var PASSTHROUGH_OPTIONS = ['http', 'description'];
+var PASSTHROUGH_OPTIONS = ['http', 'description', 'notes'];
 
 /**
  * @class A wrapper to make manipulating the exports object easier.
@@ -112,6 +112,7 @@ function method(fn, options) {
   var path = options.path || options.name || fn.name || null;
   var accepts = options.accepts || null;
   var returns = options.returns || null;
+  var errors = options.errors || null;
 
   if (!path) {
     // TODO: Error.
@@ -122,6 +123,7 @@ function method(fn, options) {
   fn.shared = true;
   fn.accepts = accepts;
   fn.returns = returns;
+  fn.errors = errors;
 
   PASSTHROUGH_OPTIONS.forEach(function (key) {
     if (options[key]) {

lib/http-context.js

@@ -47,6 +47,7 @@ HttpContext.prototype.buildArgs = function (method) {
   var ctx = this;
   var accepts = method.accepts;
   var returns = method.returns;
+  var errors = method.errors;
 
   // build arguments from req and method options
   accepts.forEach(function (o) {

lib/http-invocation.js

@@ -162,6 +162,7 @@ HttpInvocation.prototype.createRequest = function () {
   var accepts = method.accepts;
   var ctorAccepts = null;
   var returns = method.returns;
+  var errors = method.errors;
   var query;
   var i;
 
@@ -222,6 +223,7 @@ HttpInvocation.prototype.transformResponse = function(res, body, callback) {
   var callbackArgs = [null]; // null => placeholder for err
   var method = this.method;
   var returns = method.returns;
+  var errors = method.errors;
   var isObject = typeof body === 'object';
   var err;
   var hasError = res.statusCode >= 400;

lib/jsonrpc-adapter.js

@@ -217,9 +217,11 @@ JsonRpcAdapter.prototype.allRoutes = function () {
       verb: verb,
       path: path,
       description: method.description,
+      notes: method.notes,
       method: method.stringName,
       accepts: (method.accepts && method.accepts.length) ? method.accepts : undefined,
-      returns: (method.returns && method.returns.length) ? method.returns : undefined
+      returns: (method.returns && method.returns.length) ? method.returns : undefined,
+      errors: (method.errors && method.errors.length) ? method.errors : undefined
     });
   }
 };

lib/remote-objects.js

@@ -206,7 +206,8 @@ RemoteObjects.prototype.toJSON = function () {
     result[sharedMethod.stringName] = {
       http: sharedMethod.fn && sharedMethod.fn.http,
       accepts: sharedMethod.accepts,
-      returns: sharedMethod.returns
+      returns: sharedMethod.returns,
+      errors: sharedMethod.errors
     };
   });
 

lib/rest-adapter.js

@@ -455,9 +455,11 @@ RestAdapter.prototype.allRoutes = function () {
       verb: verb,
       path: path,
       description: method.description,
+      notes: method.notes,
       method: method.stringName,
       accepts: (method.accepts && method.accepts.length) ? method.accepts : undefined,
-      returns: (method.returns && method.returns.length) ? method.returns : undefined
+      returns: (method.returns && method.returns.length) ? method.returns : undefined,
+      errors: (method.errors && method.errors.length) ? method.errors : undefined
     });
   }
 }
@@ -498,7 +500,9 @@ function RestMethod(restClass, sharedMethod) {
 
   this.accepts = sharedMethod.accepts;
   this.returns = sharedMethod.returns;
+  this.errors = sharedMethod.errors;
   this.description = sharedMethod.description;
+  this.notes = sharedMethod.notes;
 
   var methodRoutes = getRoutes(sharedMethod);
   if (sharedMethod.isStatic || !restClass.ctor) {

lib/shared-class.js

@@ -167,6 +167,7 @@ function define(methods, name, options, fn) {
  *   define('myMethod', {
  *     accepts: {arg: 'str', type: 'string'},
  *     returns: {arg: 'str', type: 'string'}
+ *     errors: [ { code: 404, message: 'Not Found', responseModel: 'Error' } ]
  *   }, myMethod);
  * });
  * function myMethod(str, cb) {

lib/shared-method.js

@@ -44,13 +44,16 @@ var debug = require('debug')('strong-remoting:shared-method')
  * @param {Object} [options.accepts.rest] The REST mapping / settings for the
  * argument.
  * @param {Array|Object} [options.returns] An `Array` of argument definitions
+ * @param {Array|Object} [options.errors] An `Array` of error definitions
  * The same options are available as `options.accepts`.
  * @property {String} name The method name
  * @property {String[]} aliases An array of method aliases
  * @property {Array|Object} isStatic
  * @property {Array|Object} accepts See `options.accepts`
  * @property {Array|Object} returns See `options.returns`
+ * @property {Array|Object} errors See `options.errors`
  * @property {String} description
+ * @property {String} notes
  * @property {String} http
  * @property {String} rest
  * @property {String} shared
@@ -70,7 +73,9 @@ function SharedMethod(fn, name, sc, options) {
   var isStatic = this.isStatic = options.isStatic || false;
   this.accepts = options.accepts || fn.accepts || [];
   this.returns = options.returns || fn.returns || [];
+  this.errors = options.errors || fn.errors || [];
   this.description = options.description || fn.description;
+  this.notes = options.notes || fn.notes;
   this.http = options.http || fn.http || {};
   this.rest = options.rest || fn.rest || {};
   this.shared = options.shared;
@@ -96,6 +101,9 @@ function SharedMethod(fn, name, sc, options) {
   if(this.returns && !Array.isArray(this.returns)) {
     this.returns = [this.returns];
   }
+  if(this.errors && !Array.isArray(this.errors)) {
+    this.errors = [this.errors];
+  }
 
   this.stringName = (sc ? sc.name : '') + (isStatic ? '.' : '.prototype.') + name;
 }
@@ -115,7 +123,9 @@ SharedMethod.fromFunction = function(fn, name, sharedClass, isStatic) {
     isStatic: isStatic,
     accepts: fn.accepts,
     returns: fn.returns,
+    errors: fn.errors,
     description: fn.description,
+    notes: fn.notes,
     http: fn.http,
     rest: fn.rest
   });
@@ -131,6 +141,7 @@ SharedMethod.fromFunction = function(fn, name, sharedClass, isStatic) {
 SharedMethod.prototype.invoke = function (scope, args, fn) {
   var accepts = this.accepts;
   var returns = this.returns;
+  var errors = this.errors;
   var method = this.getFunction();
   var sharedMethod = this;
   var formattedArgs = [];

lib/socket-io-context.js

@@ -85,6 +85,7 @@ SocketIOContext.prototype.invoke = function (scope, method, fn) {
   var args = method.isSharedCtor ? this.ctorArgs : this.args;
   var accepts = method.accepts;
   var returns = method.returns;
+  var errors = method.errors;
   var scope;
   var result;
 

test/rest-adapter.test.js

@@ -122,11 +122,21 @@ describe('RestAdapter', function() {
       expect(method.returns).to.eql([anArg]);
     });
 
+    it('has `errors`', function() {
+      var method = givenRestStaticMethod({ errors: anArg });
+      expect(method.errors).to.eql([anArg]);
+    });
+
     it('has `description`', function() {
       var method = givenRestStaticMethod({ description: 'a-desc' });
       expect(method.description).to.equal('a-desc');
     });
 
+    it('has `notes`', function() {
+      var method = givenRestStaticMethod({ notes: 'some-notes' });
+      expect(method.notes).to.equal('some-notes');
+    });
+
     describe('isReturningArray()', function() {
       it('returns true when there is single root Array arg', function() {
         var method = givenRestStaticMethod({

test/rest.test.js

@@ -840,6 +840,7 @@ describe('strong-remoting-rest', function(){
             { arg: 'a', type: 'number', http: {source: 'path'} }
           ],
           returns: { arg: 'n', type: 'number', root: true},
+          errors: [],
           http: { path: '/:a' }
         }
       );