Simplify `accepts` and `returns` hacks.

lib/route-helper.js

@@ -43,18 +43,19 @@ var routeHelper = module.exports = {
    * Massage route.accepts.
    * @param  {Object} route    Strong Remoting Route object.
    * @param  {Class}  classDef Strong Remoting class.
-   * @return {Object}          Modified Route object.
+   * @return {Array}           Array of param docs.
    */
-  hackAcceptsDefinition: function hackAcceptsDefinition(route, classDef) {
+  convertAcceptsToSwagger: function convertAcceptsToSwagger(route, classDef) {
     var split = route.method.split('.');
+    var accepts = _cloneDeep(route.accepts) || [];
     if (classDef && classDef.sharedCtor && 
         classDef.sharedCtor.accepts && split.length > 2 /* HACK */) {
-      route.accepts = (route.accepts || []).concat(classDef.sharedCtor.accepts);
+      accepts = accepts.concat(classDef.sharedCtor.accepts);
     }
 
     // Filter out parameters that are generated from the incoming request,
     // or generated by functions that use those resources.
-    route.accepts = (route.accepts || []).filter(function(arg){
+    accepts = accepts.filter(function(arg){
       if (!arg.http) return true;
       // Don't show derived arguments.
       if (typeof arg.http === 'function') return false;
@@ -65,44 +66,48 @@ var routeHelper = module.exports = {
     });
 
     // Translate LDL keys to Swagger keys.
-    route.accepts = (route.accepts || []).map(translateDataTypeKeys);
+    accepts = accepts.map(translateDataTypeKeys);
 
-    return route;
+    // Turn accept definitions in to parameter docs.
+    accepts = accepts.map(routeHelper.acceptToParameter(route));
+
+    return accepts;
   },
 
   /**
    * Massage route.returns.
    * @param  {Object} route    Strong Remoting Route object.
    * @param  {Class}  classDef Strong Remoting class.
-   * @return {Object}          Modified Route object.
+   * @return {Object}          A single returns param doc.
    */
-  hackReturnsDefinition: function hackReturnsDefinition(route, classDef) {
+  convertReturnsToSwagger: function convertReturnsToSwagger(route, classDef) {
+    var routeReturns = _cloneDeep(route.returns) || [];
     // HACK: makes autogenerated REST routes return the correct model name.
-    var returns = route.returns && route.returns[0];
+    var firstReturn = routeReturns && routeReturns[0];
-    if (returns && returns.arg === 'data') {
+    if (firstReturn && firstReturn.arg === 'data') {
-      if (returns.type === 'object') {
+      if (firstReturn.type === 'object') {
-        returns.type = classDef.name;
+        firstReturn.type = classDef.name;
-      } else if (returns.type === 'array') {
+      } else if (firstReturn.type === 'array') {
-        returns.type = 'array';
+        firstReturn.type = 'array';
-        returns.items = {
+        firstReturn.items = {
           '$ref': classDef.name
         };
       }
     }
 
     // Translate LDL keys to Swagger keys.
-    route.returns = (route.returns || []).map(translateDataTypeKeys);
+    var returns = routeReturns.map(translateDataTypeKeys);
 
     // Convert `returns` into a single object for later conversion into an 
     // operation object.
-    if (route.returns && route.returns.length > 1) {
+    if (returns && returns.length > 1) {
       // TODO ad-hoc model definition in the case of multiple return values.
-      route.returns = {model: 'object'}; 
+      returns = {model: 'object'}; 
     } else {
-      route.returns = route.returns[0] || {};
+      returns = returns[0] || {};
     }
 
-    return route;
+    return returns;
   },
 
   /**
@@ -113,14 +118,10 @@ var routeHelper = module.exports = {
   routeToAPIDoc: function routeToAPIDoc(route, classDef) {
     var returnDesc;
 
-    // Don't modify the existing route as some pieces (such as `returns`) 
-    // may be shared between routes.
-    route = _cloneDeep(route);
-
     // Some parameters need to be altered; eventually most of this should 
     // be removed.
-    route = routeHelper.hackAcceptsDefinition(route, classDef);
+    var accepts = routeHelper.convertAcceptsToSwagger(route, classDef);
-    route = routeHelper.hackReturnsDefinition(route, classDef);
+    var returns = routeHelper.convertReturnsToSwagger(route, classDef);
 
     debug('route %j', route);
 
@@ -133,8 +134,8 @@ var routeHelper = module.exports = {
         // Per the spec:
         // https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#523-operation-object
         // This is the only object that may have a type of 'void'.
-        type: route.returns.model || route.returns.type || 'void',
+        type: returns.model || returns.type || 'void',
-        parameters: route.accepts.map(routeHelper.acceptToParameter(route)),
+        parameters: accepts,
         // TODO(schoon) - We don't have descriptions for this yet.
         responseMessages: [], 
         summary: route.description, // TODO(schoon) - Excerpt?