spice-js 2.7.35 → 2.7.36

package/build/docs/generator.js

@@ -19,6 +19,50 @@ function getPackageInfo() {
   var pac = require(_path2.default.join(spice.parent_app_dir, "/package.json"));
   return pac;
 }
+
+// Swagger 2.0 restricts a parameter to these types. The schema vocabulary is
+// richer ("date", "Array", model names) and anything outside this set makes the
+// parameter invalid, so Swagger UI renders no input for it at all.
+var SWAGGER_PARAMETER_TYPES = ["string", "number", "integer", "boolean", "array", "file"];
+function toParameterType(type) {
+  if (typeof type != "string") {
+    return {
+      type: "string"
+    };
+  }
+  var lowered = type.toLowerCase();
+  if (lowered == "date") {
+    return {
+      type: "string",
+      format: "date"
+    };
+  }
+  if (lowered == "datetime") {
+    return {
+      type: "string",
+      format: "date-time"
+    };
+  }
+  // Objects and collections are submitted as text in a form body
+  if (_lodash.default.includes(["object", "array"], lowered)) {
+    return {
+      type: "string"
+    };
+  }
+  if (_lodash.default.includes(SWAGGER_PARAMETER_TYPES, lowered)) {
+    return {
+      type: lowered
+    };
+  }
+  // Model references and anything unrecognised
+  return {
+    type: "string"
+  };
+}
+function trimTrailingSlash(p) {
+  if (typeof p !== "string") return p;
+  return p.length > 1 ? p.replace(/\/+$/, "") : p;
+}
 function createPath(path) {
   return _lodash.default.join(_lodash.default.map(_lodash.default.split(path, "/"), seg => {
     if (_lodash.default.startsWith(seg, ":")) {
@@ -92,18 +136,35 @@ function getRoutes(models) {
               description: "Not found"
             }
           };
-          var comment = _lodash.default.find(comment_processed, comment => {
-            function matches() {
-              var match = false;
-              match = _lodash.default.endsWith(layer.path, comment.original_path);
-              return match;
-            }
-            return comment.method == _lodash.default.lowerCase(_lodash.default.last(layer.methods)) && matches();
+
+          // koa-router drops the trailing slash when it applies a router
+          // prefix, so a route declared as router.post("/") ends up with
+          // layer.path equal to the prefix itself and never "ends with" the
+          // documented "/". That left every collection-root endpoint without
+          // its comment, and so without parameters, description or response
+          // schema. Expand the documented path against the prefix and match
+          // exactly, keeping the old suffix match as a fallback for files
+          // that document fully-qualified paths.
+          var layer_method = _lodash.default.lowerCase(_lodash.default.last(layer.methods));
+          var layer_path = trimTrailingSlash(layer.path);
+          var router_prefix = router.opts && router.opts.prefix || "";
+          var candidates = _lodash.default.filter(comment_processed, item => item.method == layer_method);
+          var comment = _lodash.default.find(candidates, item => layer_path === trimTrailingSlash(router_prefix + item.original_path)) || _lodash.default.find(candidates, item => {
+            var documented = trimTrailingSlash(item.original_path);
+            // "/" would suffix-match every path in the file
+            if (documented === "/" || documented === "") return false;
+            return _lodash.default.endsWith(layer_path, documented);
           });
           if (comment != undefined) {
             _path.description = comment.description;
             _path.operationId = _uuid.default.v4();
             _path.parameters = [...preparParameters(comment, undefined, models, router), ..._path.params];
+            // Swagger 2.0 requires an operation carrying formData parameters
+            // to declare a form media type, otherwise "Try it out" has no
+            // body to build and the fields are ignored.
+            if (_lodash.default.some(_path.parameters, param => param.in === "formData")) {
+              _path.consumes = [_lodash.default.some(_path.parameters, param => param.type === "file") ? "multipart/form-data" : "application/x-www-form-urlencoded"];
+            }
             var doc_return = filterTags(comment, "returns");
             if (doc_return.length > 0) {
               if (doc_return[0].type == undefined) {
@@ -166,14 +227,14 @@ function preparParameters(comment, defaultModel, models) {
     }
     function modelToParameter(model) {
       return _lodash.default.map(models[model], (value, key) => {
-        return {
-          name: key,
-          type: _lodash.default.includes(["object", "array"], value.type) ? "string" : value.type,
+        return _extends({
+          name: key
+        }, toParameterType(value.type), {
           description: value.description ? value.description : "",
           required: value.required ? value.required : false,
           paramType: "form",
           in: "formData"
-        };
+        });
       }).filter(obj => obj != undefined);
     }
     /* console.log("Props::::::: ", [
@@ -326,6 +387,37 @@ function generateTags() {
     };
   });
 }
+
+// An @returns tag names a model, but plenty of routes use it for prose
+// ("success status", "Providers + models"). Those become $refs that point at a
+// definition which does not exist, and Swagger UI cannot resolve them, so the
+// response renders blank. Keep the prose as a description instead.
+function pruneDanglingRefs(spec) {
+  var available = _lodash.default.keys(spec.definitions || {});
+  _lodash.default.each(spec.paths, methods => {
+    _lodash.default.each(methods, operation => {
+      var response = _lodash.default.get(operation, ["responses", "200"]);
+      if (response == undefined || response.schema == undefined) {
+        return;
+      }
+      var schema = response.schema;
+      var holder = schema.$ref != undefined ? schema : _lodash.default.get(schema, ["items", "$ref"]) != undefined ? schema.items : _lodash.default.get(schema, ["additionalProperties", "$ref"]) != undefined ? schema.additionalProperties : undefined;
+      if (holder == undefined) {
+        return;
+      }
+      var referenced = _lodash.default.last(_lodash.default.split(holder.$ref, "/"));
+      if (_lodash.default.includes(available, referenced)) {
+        return;
+      }
+      delete holder.$ref;
+      holder.type = "object";
+      if (referenced) {
+        response.description = "Successful Operation - " + referenced;
+      }
+    });
+  });
+  return spec;
+}
 function generateSpec() {
   return _generateSpec.apply(this, arguments);
 }
@@ -366,7 +458,7 @@ function _generateSpec() {
       paths: generatePaths(routes),
       definitions: generateDefinitions(models)
     };
-    return spec;
+    return pruneDanglingRefs(spec);
   });
   return _generateSpec.apply(this, arguments);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spice-js",
-  "version": "2.7.35",
+  "version": "2.7.36",
   "description": "spice",
   "main": "build/index.js",
   "repository": {

package/src/docs/generator.js

@@ -13,6 +13,45 @@ function getPackageInfo() {
   return pac;
 }
 
+// Swagger 2.0 restricts a parameter to these types. The schema vocabulary is
+// richer ("date", "Array", model names) and anything outside this set makes the
+// parameter invalid, so Swagger UI renders no input for it at all.
+const SWAGGER_PARAMETER_TYPES = [
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "array",
+  "file",
+];
+
+function toParameterType(type) {
+  if (typeof type != "string") {
+    return { type: "string" };
+  }
+  let lowered = type.toLowerCase();
+  if (lowered == "date") {
+    return { type: "string", format: "date" };
+  }
+  if (lowered == "datetime") {
+    return { type: "string", format: "date-time" };
+  }
+  // Objects and collections are submitted as text in a form body
+  if (_.includes(["object", "array"], lowered)) {
+    return { type: "string" };
+  }
+  if (_.includes(SWAGGER_PARAMETER_TYPES, lowered)) {
+    return { type: lowered };
+  }
+  // Model references and anything unrecognised
+  return { type: "string" };
+}
+
+function trimTrailingSlash(p) {
+  if (typeof p !== "string") return p;
+  return p.length > 1 ? p.replace(/\/+$/, "") : p;
+}
+
 function createPath(path) {
   return _.join(
     _.map(_.split(path, "/"), (seg) => {
@@ -100,17 +139,36 @@ function getRoutes(models) {
               },
             };
 
-            let comment = _.find(comment_processed, (comment) => {
-              function matches() {
-                let match = false;
-                match = _.endsWith(layer.path, comment.original_path);
-                return match;
-              }
-              return (
-                comment.method == _.lowerCase(_.last(layer.methods)) &&
-                matches()
-              );
-            });
+            // koa-router drops the trailing slash when it applies a router
+            // prefix, so a route declared as router.post("/") ends up with
+            // layer.path equal to the prefix itself and never "ends with" the
+            // documented "/". That left every collection-root endpoint without
+            // its comment, and so without parameters, description or response
+            // schema. Expand the documented path against the prefix and match
+            // exactly, keeping the old suffix match as a fallback for files
+            // that document fully-qualified paths.
+            let layer_method = _.lowerCase(_.last(layer.methods));
+            let layer_path = trimTrailingSlash(layer.path);
+            let router_prefix = (router.opts && router.opts.prefix) || "";
+
+            let candidates = _.filter(
+              comment_processed,
+              (item) => item.method == layer_method
+            );
+
+            let comment =
+              _.find(
+                candidates,
+                (item) =>
+                  layer_path ===
+                  trimTrailingSlash(router_prefix + item.original_path)
+              ) ||
+              _.find(candidates, (item) => {
+                let documented = trimTrailingSlash(item.original_path);
+                // "/" would suffix-match every path in the file
+                if (documented === "/" || documented === "") return false;
+                return _.endsWith(layer_path, documented);
+              });
 
             if (comment != undefined) {
               path.description = comment.description;
@@ -119,6 +177,18 @@ function getRoutes(models) {
                 ...preparParameters(comment, undefined, models, router),
                 ...path.params,
               ];
+              // Swagger 2.0 requires an operation carrying formData parameters
+              // to declare a form media type, otherwise "Try it out" has no
+              // body to build and the fields are ignored.
+              if (_.some(path.parameters, (param) => param.in === "formData")) {
+                path.consumes = [
+                  (
+                    _.some(path.parameters, (param) => param.type === "file")
+                  ) ?
+                    "multipart/form-data"
+                  : "application/x-www-form-urlencoded",
+                ];
+              }
               let doc_return = filterTags(comment, "returns");
               if (doc_return.length > 0) {
                 if (doc_return[0].type == undefined) {
@@ -185,8 +255,7 @@ function preparParameters(comment, defaultModel, models) {
       return _.map(models[model], (value, key) => {
         return {
           name: key,
-          type:
-            _.includes(["object", "array"], value.type) ? "string" : value.type,
+          ...toParameterType(value.type),
           description: value.description ? value.description : "",
           required: value.required ? value.required : false,
           paramType: "form",
@@ -353,6 +422,42 @@ function generateTags() {
   });
 }
 
+// An @returns tag names a model, but plenty of routes use it for prose
+// ("success status", "Providers + models"). Those become $refs that point at a
+// definition which does not exist, and Swagger UI cannot resolve them, so the
+// response renders blank. Keep the prose as a description instead.
+function pruneDanglingRefs(spec) {
+  let available = _.keys(spec.definitions || {});
+  _.each(spec.paths, (methods) => {
+    _.each(methods, (operation) => {
+      let response = _.get(operation, ["responses", "200"]);
+      if (response == undefined || response.schema == undefined) {
+        return;
+      }
+      let schema = response.schema;
+      let holder =
+        schema.$ref != undefined ? schema
+        : _.get(schema, ["items", "$ref"]) != undefined ? schema.items
+        : _.get(schema, ["additionalProperties", "$ref"]) != undefined ?
+          schema.additionalProperties
+        : undefined;
+      if (holder == undefined) {
+        return;
+      }
+      let referenced = _.last(_.split(holder.$ref, "/"));
+      if (_.includes(available, referenced)) {
+        return;
+      }
+      delete holder.$ref;
+      holder.type = "object";
+      if (referenced) {
+        response.description = `Successful Operation - ${referenced}`;
+      }
+    });
+  });
+  return spec;
+}
+
 export default async function generateSpec() {
   let { description, version, name } = getPackageInfo();
   let models = _.cloneDeep(await getModels());
@@ -392,5 +497,5 @@ export default async function generateSpec() {
     paths: generatePaths(routes),
     definitions: generateDefinitions(models),
   };
-  return spec;
+  return pruneDanglingRefs(spec);
 }