express-api-docs - npm Package Compare versions

Comparing version 0.0.2 to 0.0.3

make-api-docs.js

@@ -12,6 +12,9 @@ /**
 
-var files = [];
-var funcs = {};
-var output = { entries: [] };
+var files     = [];
+var resources = [];
+var funcs     = {};
 
+// TODO: Remove this global variable and pass the values around...
+var output    = { entries: [] };
+
 /**
@@ -41,3 +44,3 @@ * Reads a file containing Express routes. This function/behavior is
     if (!inputFile) {
-        inputFile  = "./router.js";
+        inputFile  = "./app.js";
     }
@@ -51,3 +54,8 @@ if (!outputFile) {
 
-    // console.log(files);
+    // if (files.length > 0) {
+    //     console.log(files);
+    // }
+    // if (resources.length > 0) {
+    //     console.log(resources);
+    // }
     // console.log(funcs);
@@ -59,5 +67,15 @@
     
+    resources.forEach( function(resource) {
+        analyzeResource(resource);
+    });
+
     writeFile(outputFile);
 };
 
+/**
+ * Combines a *template* with the model (stored in `output`) and writes
+ * out to a given file.
+ * 
+ * @param file {String} the name of the output file
+ */
 var writeFile = function(file) {
@@ -68,9 +86,14 @@ var data = fs.readFileSync ( __dirname + '/template.html', 'utf8');
     // console.log(output);
-
     fs.writeFileSync(file, template(output) );
 };
 
+/**
+ * Walks through a top-level source code, line-by-line, and attempts
+ * to *parse* the file by using a collection of regular expressions to
+ * match particular 'patterns' that express and express-resource specifies.
+ */
+
 var parseRoutes = function(data) {
     data.split(/\n+/).forEach( function(line) {
-        var r = /^\s*var\s*([A-Za-z0-9]+)\s*=\s*require\s*\(['"]([^'"]+)['"]\);/.exec(line);
+        var r = /^\s*var\s*([A-Za-z0-9]+)\s*=\s*require\s*\(['"]([^'"]+)['"]\s*\)\s*;/.exec(line);
         if ( r ) {
@@ -83,3 +106,3 @@ files.push({
         var a = /^\s*app\.([A-Za-z0-9]+)\s*\(\s*['"]([^'"]+)['"]\s*,\s*([^.]+)\.([^\) ]+)/.exec(line);
-        if ( a ) {
+        if ( a && a[1] !== 'resource' ) {
             funcs[ a[4] ] = {
@@ -92,9 +115,22 @@ method: a[1],
         }
+        
+        // Express resource lines look like:
+        //   app.resource('user', require('./resources/user'));
+        var rsc = /^\s*app\.resource\s*\(\s*['"]([^'"]+)['"]\s*,\s*require\s*\(['"]([^'"]+)['"]\s*\)\s*\)\s*;/.exec(line);
+        if ( rsc ) {
+            resources.push({
+                rsc : rsc[1],
+                file: rsc[2]
+            });
+        }
+
     });
 };
 
-//
-// Function called for each file mentioned in the `router.js` file.
-//
-
+/**
+ * Called for each file listed in the 'files' array. This will analyze and
+ * parse the files functions and comments.
+ *
+ * @param file (String) The name of the file, with or without the final '.js'
+ */
 var analyzeFile = function(file) {
@@ -118,6 +154,16 @@
 
-//
-// Function called for each route referenced in the file, 
-// 
 
+/**
+ * Function called for each route referenced in the file.
+ * 
+ * For each route referenced, we build up part of the "model" that will be
+ * passed to the template engine for display.
+ * 
+ * **Note:** Doesn't return anything, but side effects include modifying the
+ * `output` object model.
+ * 
+ * @param {String} name route name that should be part of `funcs[]` array
+ * @param {Object} details acquired by `dox.parse`. Expects a `description` property.
+ */ 
+
 var createRoute = function(name, details) {
@@ -139,2 +185,105 @@
     }
+};
+
+/**
+ * Called for each file listed in the 'resource' array. This will analyze and
+ * parse the files functions and comments.
+ *
+ * @param resource (String) The name of the file, with or without the final '.js'
+ */
+var analyzeResource = function(resource) {
+
+    var label    = resource.rsc;
+    var filename = resource.file;
+    if ( ! /\.js$/.test(filename) ) {
+        filename = filename + '.js';
+    }
+    
+    try {
+        var js = fs.readFileSync(filename, 'utf8');
+        var d = dox.parseComments(js);
+        
+        d.forEach( function(entry) {
+            if (   entry.ctx && 
+                    ( entry.ctx.type == 'method' || entry.ctx.type == 'function') ) {
+                console.log("Working on API docs for resource: %s", entry.ctx.name);
+                var model = createResource(label, entry);
+                if (model) {
+                    output.entries.push( model );
+                }
+            }
+        });
+    }
+    catch (err) {
+        console.warn( err );
+    }
+};
+
+/**
+ * Function called for each resource referenced in the file.
+ * 
+ * For each resource referenced, we build up part of the "model" that will be
+ * passed to the template engine for display. Of course, with `express-resource`
+ * the names of the function *imply* a particular route, as in:
+ * 
+ *  - GET     /label          ->  index
+ *  - GET     /label/new      ->  new
+ *  - POST    /label          ->  create
+ *  - GET     /label/ID       ->  show
+ *  - GET     /label/ID/edit  ->  edit
+ *  - PUT     /label/ID       ->  update
+ *  - DELETE  /label/ID       ->  destroy
+ * 
+ * Where `label` is the name of the resource that is passed in, and `ID` is
+ * an identification of the resource.
+ * 
+ * @param {String} label resource name that should be part of route
+ * @param {Object} entry acquired by `dox.parse`. Expects a `description` property.
+ * @returns {Object} a model entry that can be pushed into the `output`
+ */ 
+
+var createResource = function(label, entry) {
+    var name   = entry.ctx.name;
+    var method = 'GET';
+    var route  = '/' + label;
+    
+    switch(entry.ctx.name) {
+        case 'index':
+            method = 'GET';
+            route  = '/' + label;
+            break;
+        case 'new':
+            method = 'GET';
+            route  = '/' + label + '/new';
+            break;
+        case 'create':
+            method = 'POST';
+            route  = '/' + label;
+            break;
+        case 'show':
+            method = 'GET';
+            route  = '/' + label + '/<ID>';
+            break;
+        case 'edit':
+            method = 'GET';
+            route  = '/' + label + '/<ID>/edit';
+            break;
+        case 'update':
+            method = 'PUT';
+            route  = '/' + label + '/<ID>';
+            break;
+        case 'destroy':
+            method = 'DELETE';
+            route  = '/' + label + '/<ID>';
+            break;
+        default:
+            return;
+    }
+    
+    return {
+        "name":   name,
+        "method": method,
+        "route":  route,
+        "text":   entry.description.full
+    };
 };

package.json

@@ -5,3 +5,3 @@ {
   "description": "Generates an API document from code built with Express",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "homepage": "http://www.github.com/howardabrams/express-api-docs",
@@ -8,0 +8,0 @@ "keywords": [

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

35048

increased by135.32%

Number of package files

17

increased by70%

Lines of code

711

increased by89.6%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes