Support hiding entry points with x-hidden

This patch adds a small, private extension that lets us hide private entry
points from the docs by adding an `x-hidden` boolean property at the method
level. This is occasionally useful for "boilerplate" entry points like /robots.txt.

There are discussions about more advanced ACL-based doc hiding at
OAI/OpenAPI-Specification#433, but those haven't
lead anywhere yet. This is a simple solution that will work in the meantime.

lib/router.js

@@ -283,22 +283,22 @@ Router.prototype._loadModules = function(node, hyperModules, scope, parentSegmen
  */
 Router.prototype._registerMethods = function(node, pathspec, scope) {
     var self = this;
-    // Register the path in the specRoot
-    if (scope.specRoot && !scope.specRoot.paths[scope.prefixPath]
-            // But don't load empty paths.
-            && scope.prefixPath) {
-        scope.specRoot.paths[scope.prefixPath] = {};
-    }
 
     Object.keys(pathspec).forEach(function(methodName) {
         if (/^x-/.test(methodName)) {
             return;
         }
         var method = pathspec[methodName];
+        var specPaths = scope.specRoot.paths;
         // Insert the method spec into the global merged spec
-        if (scope.specRoot.paths[scope.prefixPath] && methodName
-                && !scope.specRoot.paths[scope.prefixPath][methodName]) {
-            scope.specRoot.paths[scope.prefixPath][methodName] = method;
+        if (method && !method['x-hidden']
+                && (!specPaths[scope.prefixPath]
+                    || !specPaths[scope.prefixPath][methodName])) {
+            // Register the path in the specRoot
+            if (!specPaths[scope.prefixPath]) {
+                specPaths[scope.prefixPath] = {};
+            }
+            specPaths[scope.prefixPath][methodName] = method;
         }
 
         if (node.value.methods.hasOwnProperty(methodName)) {
@@ -352,10 +352,12 @@ Router.prototype._createNewApiRoot = function(node, spec, scope) {
     var specRoot = Object.assign({}, spec);
     // Make sure the spec has the standard properties set up.
     specRoot.swagger = spec.swagger || '2.0';
-    specRoot.paths = spec.paths || {};
     specRoot.definitions = spec.definitions || {};
     specRoot.securityDefinitions = spec.securityDefinitions || {};
     specRoot['x-default-params'] = spec['x-default-params'] || {};
+
+    // Reset paths. These are going to be built up during path setup.
+    specRoot.paths = {};
     specRoot.basePath = scope.prefixPath;
 
     node.setChild('', new Node({