praxis 0.20.1 → 0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3cc6641a8ee79fff261135fc27c46987c5118963
-  data.tar.gz: 23e6e0f445620738409e10818044f66f923c940a
+  metadata.gz: d0a0928d3b9a59294d32767a333b73c03a0a7955
+  data.tar.gz: 840261c0c55f18280f3c32d53a62053ed8582834
 SHA512:
-  metadata.gz: 2f956167d5bf702c127b12b632a1b4d7ac3a404088d9f1fc226c813ffcd5bb93d4c857747bcd24acd07f449fb4123240e768716c0f433182588fd33d85143682
-  data.tar.gz: 956e4d47a1b7fecdb9f41da2343422f1f243b777b64402fccd9fd3c2e92a0b878b2c907f7c79d39b7d38b1a81f2a8a7564fc5f80ad43acce3144d778c46c6b6f
+  metadata.gz: 2c7d30737b31ec8204e030ca43577d8a4620b4a16ee3f9ec00c40ef740f08db8c7c21d9bc1d06dc7ddc56e2223dc0f9aaa990526a6f92f7297493dcf02158c11
+  data.tar.gz: b1e794d55ef40a616c21adeb8a72cea53b796e4a943636c5a16a576f282298c6f573b730f708ab2a0bbb050784c56c3b1fe53f760488c3100d98958a2b50f6eb

data/.ruby-version

@@ -1 +1 @@
-2.2.2
+2.3

data/.travis.yml

@@ -2,8 +2,8 @@ language: ruby
 cache: bundler
 sudo: false
 rvm:
-  - 2.1.5
-  - 2.2.2
+  - 2.2.5
+  - 2.3.1
 node_js:
   - "0.10"
 branches:

data/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## next
 
+## 0.21
+
+* Protect against `MediaType`s that do not have any links defined.
+* More robust scanning of existing types when generating docs. Some types might have not been
+  properly reported in the `schemas` section of the JSON docs if they were only used somewhere
+  deep in some other type or action hierarchy
+* Build doc browser support for defining top-level home pages for types.
+  Apps can achieve the override by registering templates that respond to the ‘main’ type (instead of
+  the other existing ‘label’,’embedded’ and ‘standalone’ modes).
+* Enhance doc browser to show header and location expectations on action responses that have them
+  defined
+* Allow Plugin registration without requiring config_key
+  * registration will select a default config_key based on the class name
+* A new `documentation_url` global directive is exposed for authors to be able to
+  indicate where documentation will be hosted.
+  * If this is provided, the default *validation handler* will add a `documentation`
+    key to the response pointing at a url that should correspond to the documentation
+    for the resource the user was requesting.
+  * `Praxis::Docs::LinkBuilder` can be used to generate these documentation urls from
+    the praxis application.
+* You can now switch your doc browser to use HTML5 style urls (i.e.
+  `/1.0/type/V1-MediaTypes-PriceFilter` instead of
+  `/index.html#/1.0/type/V1-MediaTypes-PriceFilter`).
+* Remove deprecated rake tasks.
+* Remove some remaining inline styling in doc browser.
+* Adds a `ExampleProvider.removeHandlersForKey` call. You can use `ExampleProvider.removeHandlersForKey('general')`
+  to get rid of the default example if required.
+* Make Traits accumulate block definitions for `params`,`headers` and `payload` rather than overriding them.
+* Switch to lazy evaluation of `base_params` from `ApiDefinition` to properly inherit them into the resources
+  and their corresponding actions even before the application's `MediaTtypes` have been finalized.
+* Built the `MiddlewareApp` class to make it easy to run a Praxis app mounted as an intercepting
+  middleware which will only forward requests down the stack if they didn't match any of its routes.
+  * Note: it properly skips forwarding when 404s are purposedly returned by the application itself.
+  * Note2: it also respects the `X-Cascade=pass` conventions.
+
+
 ## 0.20.1
 
 * Doc generation: handle SimpleMediaTypes so that they don’t show up in the generated schemas.

data/lib/api_browser/Gruntfile.js

@@ -13,7 +13,8 @@ module.exports = function(grunt) {
       pluginPaths  = process.env.PLUGIN_PATHS ? process.env.PLUGIN_PATHS.split(':') : [],
       buildPath    = userDocsPath + '/output',
       browserPort  = process.env.DOC_PORT || '9090',
-      bowerPaths   = pluginPaths.concat([userDocsPath]).map(function(f) { return f + '/bower.json'; });
+      bowerPaths   = pluginPaths.concat([userDocsPath]).map(function(f) { return f + '/bower.json'; }),
+      basePath     = process.env.BASE_PATH || '';
 
   var cssOutput = {};
   cssOutput[buildPath + '/css/main.css'] = userDocsPath + '/styles.scss';
@@ -75,7 +76,28 @@ module.exports = function(grunt) {
             '.tmp',
             '.data',
             'app'
-          ])
+          ]),
+          // This is to handle support of using $locationProvider.html5Mode(true).
+          middleware: function(connect, options, middlewares) {
+            middlewares.push(function(req, res, next) {
+              var segments = require('url').parse(req.url).pathname.split('/'),
+                  last = segments[segments.length - 1];
+              if (last.split('.').length === 1) {
+                try {
+                  var index = grunt.file.read('.tmp/index.html');
+                  res.setHeader("Content-Type", "text/html");
+                  res.write(index, 'utf8');
+                  res.end()
+                } catch(e) {
+                  next(e);
+                }
+              } else {
+                next();
+              }
+            });
+
+            return middlewares;
+          }
         }
       },
       dist: {
@@ -362,7 +384,15 @@ module.exports = function(grunt) {
       html: [buildPath + '/index.html'],
       css: [buildPath + '/css/{,*/}*.css'],
       options: {
-        assetsDirs: [buildPath]
+        assetsDirs: [buildPath],
+        blockReplacements: {
+          base: function(block) {
+            if (basePath !== '') {
+              return '<base href="' + basePath + '">';
+            }
+            return '';
+          }
+        }
       }
     },
 

data/lib/api_browser/app/index.html

@@ -6,6 +6,9 @@
   <title ng-bind="subtitle ? title + ' – ' + subtitle : title">API Browser</title>
   <meta name="description" content="">
   <meta name="viewport" content="width=device-width">
+  <!-- build:base base -->
+  <base src="/">
+  <!-- endbuild -->
   <!-- build:css({.tmp,app,/}) css/other.css -->
   <!-- bower:css -->
   <!-- endbower -->

data/lib/api_browser/app/js/factories/Example.js

@@ -10,6 +10,10 @@ app.provider('Examples', function() {
     });
   };
 
+  this.removeHandlersForKey = function(key) {
+    registry[key] = [];
+  };
+
   this.register('general', 'General', function() {
     return 'views/examples/general.html';
   });

data/lib/api_browser/app/js/factories/template_for.js

@@ -80,6 +80,20 @@ app.provider('templateFor', function() {
     }
   });
 
+  this.register(function mainPageResolver($family, $requestedTemplate) {
+    'ngInject';
+    if ($requestedTemplate === 'main') {
+      switch ($family) {
+        case 'hash':
+          return 'views/types/main/hash.html';
+        case 'array':
+          return 'views/types/main/array.html';
+        default:
+          return 'views/types/main/default.html';
+      }
+    }
+  });
+
   this.$get = function($injector, prepareTemplate) {
     return function(type, templateType) {
       for (var i = 0; i < resolvers.length; i++) {

data/lib/api_browser/app/js/filters/attribute_name.js

@@ -1,8 +1,9 @@
 app.filter('attributeName', function($sce) {
   return function(input) {
     var parts = input.split('.');
-    if (parts.length == 2) {
-      return $sce.trustAsHtml('<span class="attribute-prefix">' + parts[0] + '.</span>' + parts[1]);
+    if (parts.length > 1) {
+      var prefix = _.take(parts, parts.length-1).join('.');
+      return $sce.trustAsHtml('<span class="attribute-prefix">' + prefix + '.</span>' + _.last(parts));
     }
     return $sce.trustAsHtml(input);
   };

data/lib/api_browser/app/js/filters/header_info.js

@@ -0,0 +1,9 @@
+app.filter('headerInfo', function() {
+  return function(info) {
+    if (info.value !== true) {
+      return info.value + ' (' + info.type + ')';
+    } else {
+      return '(any value)';
+    }
+  };
+});

data/lib/api_browser/app/views/action.html

@@ -56,12 +56,21 @@
                 <h5>Description</h5>
                 <div ng-bind-html="response.description | markdown"></div>
               </div>
-              <h5>Status</h5>
-              <p>{{ response.status }}</p>
+              <h5>Status: {{ response.status }}</h5>
               <div ng-if="response.examples.json">
                 <h5>Content-Type</h5>
                 <p>{{ response.examples.json.content_type }}</p>
               </div>
+              <div ng-if="response.location">
+                <h5>Location:</h5>
+                <p>{{response.location.value}} <em>({{response.location.type}})</em></p>
+              </div>
+              <div ng-hide="response.headers | isEmpty">
+                <h5>Headers:</h5>
+                <div ng-repeat="(hname, hinfo) in response.headers">
+                  <p> {{hname}}: {{ hinfo | headerInfo }}</p>
+                </div>
+              </div>
               <div ng-if="response.payload.id">
                 <h5>Media Type</h5>
                 <p><type-placeholder template="label" type="response.payload"></type-placeholder></p>

data/lib/api_browser/app/views/controller.html

@@ -5,7 +5,7 @@
   <div class="row">
     <div class="col-lg-12">
       <h1 class="page-header">
-        {{ controller.name | resourceName }}
+        {{ controller.display_name || (controller.name | resourceName) }}
       </h1>
 
       <p ng-bind-html="controller.description | markdown"></p>
@@ -16,7 +16,7 @@
       </p>
     </div>
   </div>
-  <div class="row" ng-if="controller.actions.length">
+  <div class="row actions-overview" ng-if="controller.actions.length">
     <div class="col-lg-12">
       <h2>Actions</h2>
       <div class="table-responsive">
@@ -30,13 +30,13 @@
         </thead>
         <tbody>
           <tr ng-repeat="action in controller.actions">
-            <td>
+            <td class="action-overview-name">
               <a ui-sref="root.action({action: action.name, controller: controllerName, version: apiVersion})">{{ action.name }}</a>
             </td>
-            <td>
+            <td class="action-overview-url">
               <url action="action"></url>
             </td>
-            <td style="font-size: 110%;">
+            <td class="action-overview-description">
               <p ng-bind-html="action.description | markdown"></p>
             </td>
           </tr>

data/lib/api_browser/app/views/menu.html

@@ -2,7 +2,7 @@
   <div class="row">
     <div class="col-sm-12">
       <p>
-        <div ng-if="versions.length > 1" dropdown auto-close="outsideClick">
+        <div ng-if="versions.length > 1" dropdown dropdown-append-to-body>
           <button type="button" class="btn btn-success" dropdown-toggle ng-disabled="disabled">
             {{:: versionLabel}}: {{selectedVersion}} <span class="caret"></span>
           </button>

data/lib/api_browser/app/views/type.html

@@ -1,25 +1,6 @@
-<!-- Type -->
-
-<div ng-if="error" class="alert alert-danger">
-  <p>The requested type could not be found.</p>
-</div>
-<div ng-if="type">
-  <div class="row">
-    <div class="col-lg-12">
-      <h1>
-        {{ type.name | resourceName }}
-      </h1>
-    </div>
-  </div>
-  <div class="row" ng-if="controllers.length">
-    <div class="col-lg-12">
-      <h3>Served by</h3>
-      <ul>
-        <li ng-repeat="controller in controllers">
-          <a ui-sref="root.controller({version: apiVersion, controller: controller.id})">{{ controller.name | resourceName }}</a>
-        </li>
-      </ul>
-    </div>
+<div ng-if="type">
+  <div ng-if="error" class="alert alert-danger">
+    <p>The requested type could not be found.</p>
   </div>
-  <ng-include src="'views/type/details.html'" />
+  <type-placeholder type="type" template="main" details="type.attributes"></type-placeholder>
 </div>

data/lib/api_browser/app/views/type/details.html

@@ -1,10 +1,13 @@
 <div class="row" ng-if="type">
   <div class="col-lg-12">
-    <h2>Schema</h2>
-    <p ng-if="type.identifier"><b>Media-type identifier: {{ type.identifier }}</b></p>
-    <div ng-if="type.description" ng-bind-html="type.description | markdown"></div>
+    <div ng-if="type.attributes">
+      <h2>Schema</h2>
+      <p ng-if="type.identifier"><b>Media-type identifier: {{ type.identifier }}</b></p>
+      <div ng-if="type.description" ng-bind-html="type.description | markdown"></div>
 
-    <attribute-table attributes="type.attributes"></attribute-table>
+      <attribute-table attributes="type.attributes"></attribute-table>
+    </div>
+    <div ng-if="type.attributes === undefined" type-placeholder type="type" template="standalone" name="type.name" details="type"></div>
   </div>
 </div>
 <div class="row" ng-if="views.length">

data/lib/api_browser/app/views/types/main/array.html

@@ -0,0 +1,22 @@
+<div ng-if="type">
+  <div class="row">
+    <div class="col-lg-12">
+      <h1>
+        {{ type.name | resourceName }}
+      </h1>
+    </div>
+  </div>
+  <div class="row" ng-if="controllers.length">
+    <div class="col-lg-12">
+      <h3>Served by</h3>
+      <ul>
+        <li ng-repeat="controller in controllers">
+          <a ui-sref="root.controller({version: apiVersion, controller: controller.id})">{{ controller.name | resourceName }}</a>
+        </li>
+      </ul>
+    </div>
+  </div>
+  <p>A Collection of:</p>
+
+  <type-placeholder type="type.member_attribute.type" template="standalone" details="type.member_attribute.type.attributes"></type-placeholder>
+</div>

data/lib/api_browser/app/views/types/main/default.html

@@ -0,0 +1,23 @@
+<div ng-if="error" class="alert alert-danger">
+  <p>The requested type could not be found.</p>
+</div>
+<div ng-if="type">
+  <div class="row">
+    <div class="col-lg-12">
+      <h1>
+        {{ type.name | resourceName }}
+      </h1>
+    </div>
+  </div>
+  <div class="row" ng-if="controllers.length">
+    <div class="col-lg-12">
+      <h3>Served by</h3>
+      <ul>
+        <li ng-repeat="controller in controllers">
+          <a ui-sref="root.controller({version: apiVersion, controller: controller.id})">{{ controller.name | resourceName }}</a>
+        </li>
+      </ul>
+    </div>
+  </div>
+  <ng-include src="'views/type/details.html'" />
+</div>

data/lib/api_browser/app/views/types/main/hash.html

@@ -0,0 +1,23 @@
+<div ng-if="error" class="alert alert-danger">
+  <p>The requested type could not be found.</p>
+</div>
+<div ng-if="type">
+  <div class="row">
+    <div class="col-lg-12">
+      <h1>
+        {{ type.name | resourceName }}
+      </h1>
+    </div>
+  </div>
+  <div class="row" ng-if="controllers.length">
+    <div class="col-lg-12">
+      <h3>Served by</h3>
+      <ul>
+        <li ng-repeat="controller in controllers">
+          <a ui-sref="root.controller({version: apiVersion, controller: controller.id})">{{ controller.name | resourceName }}</a>
+        </li>
+      </ul>
+    </div>
+  </div>
+  <ng-include src="'views/type/details.html'" />
+</div>

data/lib/praxis.rb

@@ -45,10 +45,12 @@ module Praxis
 
   autoload :Stats, 'praxis/stats'
   autoload :Notifications, 'praxis/notifications'
+  autoload :MiddlewareApp, 'praxis/middleware_app'
 
   autoload :RestfulDocGenerator, 'praxis/restful_doc_generator'
   module Docs
     autoload :Generator, 'praxis/docs/generator'
+    autoload :LinkBuilder, 'praxis/docs/link_builder'
   end
 
   # types

data/lib/praxis/action_definition.rb

@@ -118,14 +118,6 @@ module Praxis
         update_attribute(@params, opts, block)
       else
         @params = create_attribute(type, **opts, &block)
-        if (api_info = ApiDefinition.instance.info(resource_definition.version))
-          if api_info.base_params
-            base_attrs = api_info.base_params.attributes
-            @params.attributes.merge!(base_attrs) do |key, oldval, newval|
-              oldval
-            end
-          end
-        end
       end
 
       @params

data/lib/praxis/api_definition.rb

@@ -92,17 +92,22 @@ module Praxis
     end
 
     define do |api|
-      api.response_template :ok do |media_type: |
-        media_type media_type
+      api.response_template :ok do |media_type: , location: nil, headers: nil, description: nil |
         status 200
-        description 'Standard response for successful HTTP requests.'
+        description( description || 'Standard response for successful HTTP requests.' )
+
+        media_type media_type
+        location location
+        headers headers if headers
       end
 
-      api.response_template :created do |location: nil, media_type: nil|
+      api.response_template :created do |media_type: nil, location: nil, headers: nil, description: nil|
+        status 201
+        description( description || 'The request has been fulfilled and resulted in a new resource being created.' )
+
         media_type media_type if media_type
         location location
-        status 201
-        description 'The request has been fulfilled and resulted in a new resource being created.'
+        headers headers if headers
       end
     end