praxis 0.0.1 → 0.9

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

@@ -0,0 +1,83 @@
+<!-- Action -->
+
+<div ng-if="error" class="alert alert-danger">
+  <p>The requested action could not be found.</p>
+</div>
+<div ng-if="action">
+  <div class="row">
+    <div class="col-lg-12">
+      <h1>
+        {{ action.name }}
+      </h1>
+      <p ng-repeat="url in action.urls">
+        {{ url.verb }} {{ url.path }}
+      </p>
+      <p>{{ action.description }}</p>
+    </div>
+  </div>
+
+  <div class="row" ng-if="action.headers.type.attributes">
+    <div class="col-lg-12">
+      <h2>Request Headers</h2>
+      <rs-request-headers headers="action.headers"></rs-request-headers>
+      <!--<rs-attribute-table attributes="action.headers.type.attributes" show-groups="true"></rs-attribute-table>-->
+    </div>
+  </div>
+
+  <div class="row" ng-if="action.params.type.attributes">
+    <div class="col-lg-12">
+      <h2>Request Parameters</h2>
+      <rs-request-parameters parameters="action.params"></rs-request-parameters>
+      <!--<rs-attribute-table attributes="action.params.type.attributes" show-groups="true"></rs-attribute-table>-->
+    </div>
+  </div>
+
+  <div class="row" ng-if="action.payload.type">
+    <div class="col-lg-12">
+      <h2>Request Body</h2>
+      <rs-request-body payload="action.payload"></rs-request-body>
+      <!--<rs-attribute-table attributes="action.payload.type.attributes" show-groups="true"></rs-attribute-table>-->
+    </div>
+  </div>
+
+  <div class="row" ng-if="hasResponses()">
+    <div class="col-lg-12">
+      <h2>Responses</h2>
+      <div class="attribute-table">
+        <div class="row head">
+          <div class="col-sm-2">
+            Code
+          </div>
+          <div class="col-sm-2">
+            Name
+          </div>
+          <div class="col-sm-4">
+            Media Type
+          </div>
+          <div class="col-sm-4">
+            Description
+          </div>
+        </div>
+        <div class="content">
+          <div class="row" ng-repeat="response in responses">
+            <div class="col-sm-2">
+              <span ng-if="response.isMultipart">
+                <em>Parts Like:</em>
+              </span>
+              <span>{{response.status}}</span>
+            </div>
+            <div class="col-sm-2">
+              {{response.name}}
+            </div>
+            <div class="col-sm-4">
+              {{response.media_type.name || response.media_type.identifier}}
+            </div>
+            <div class="col-sm-4">
+              <rs-attribute-description attribute="response"></rs-attribute-description>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>

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

@@ -0,0 +1,24 @@
+<!-- Controller -->
+
+<div ng-if="error" class="alert alert-danger">
+  <p>The requested controller could not be found.</p>
+</div>
+<div ng-if="controller">
+  <div class="row">
+    <div class="col-lg-12">
+      <h1 class="page-header">
+        {{ controllerName | resourceName }}
+      </h1>
+      <p>{{ controller.description }}</p>
+    </div>
+  </div>
+  <div class="row" ng-if="controller.actions.length">
+    <div class="col-lg-12">
+      <h2>Actions</h2>
+      <ng-include src="'views/resource/_actions.html'" />
+    </div>
+  </div>
+  <div ng-if="controller.media_type" ng-controller="TypeCtrl">
+    <ng-include src="'views/type/_details.html'" />
+  </div>
+</div>

data/lib/api_browser/app/views/directives/attribute_description/_default.html

@@ -0,0 +1,2 @@
+<dt>{{row.name}}</dt>
+<dd>{{row.value}}</dd>

data/lib/api_browser/app/views/directives/attribute_description/_example.html

@@ -0,0 +1,8 @@
+<dt ng-if="row.value.length < 250">example</dt>
+<dt ng-if="row.value.length >= 250">
+  <a ng-init="row.isCollapsed = true" ng-click="row.isCollapsed = !row.isCollapsed">example (click to {{row.isCollapsed? 'expand' : 'collapse'}})</a>
+</dt>
+<dd ng-if="row.value.length <= 50"><code>{{row.value}}</code></dd>
+<dd ng-if="row.value.length > 50">
+  <pre ng-class="{hide: row.isCollapsed}">{{row.value}}</pre>
+</dd>

data/lib/api_browser/app/views/directives/attribute_description/_headers.html

@@ -0,0 +1,8 @@
+<dt ng-hide="row.value | isEmpty">{{row.name}}</dt>
+<dd ng-hide="row.value | isEmpty">
+	<div ng-repeat="(k,v) in row.value">
+		<span>{{k}}:</span>
+		<span ng-if="v.value === true"><em>Any value</em></span>
+		<span ng-if="v.value !== true">{{v.value}}</span>
+	</div>
+</dd>

data/lib/api_browser/app/views/directives/attribute_description.html

@@ -0,0 +1,2 @@
+{{attribute.description}}
+<dl></dl>

data/lib/api_browser/app/views/directives/attribute_table.html

@@ -0,0 +1,23 @@
+<div class="attribute-table">
+  <div class="row head">
+    <div class="col-sm-3">
+      Attribute
+    </div>
+    <div class="col-sm-2">
+      Type
+    </div>
+    <div class="col-sm-7">
+      Description
+    </div>
+  </div>
+  <div class="content">
+    <div ng-repeat="g in groups">
+      <div class="row" ng-if="g.name && g.attributes.length">
+        <div class="col-sm-12">
+          <strong>{{g.name}}</strong>
+        </div>
+      </div>
+      <rs-attribute-table-row ng-repeat="item in g.attributes" name="item.name" attribute="item"></rs-attribute-table-row>
+    </div>
+  </div>
+</div>

data/lib/api_browser/app/views/directives/attribute_table_row/_default.html

@@ -0,0 +1,10 @@
+<div class="row">
+  <div class="col-sm-3" ng-bind-html="name | attributeName">
+  </div>
+  <div class="col-sm-2">
+    <rs-type-label type="attribute.type"></rs-type-label>
+  </div>
+  <div class="col-sm-7">
+    <rs-attribute-description attribute="attribute"></rs-attribute-description>
+  </div>
+</div>

data/lib/api_browser/app/views/directives/attribute_table_row/_links.html

@@ -0,0 +1,10 @@
+<ng-include src="'views/directives/attribute_table_row/_default.html'" no-container></ng-include>
+<div class="row" ng-repeat="(k,v) in attribute.options.dsl_compiler_options.links">
+  <div class="col-sm-3" ng-bind-html="name + '.' + k | attributeName">
+  </div>
+  <div class="col-sm-2">
+  </div>
+  <div class="col-sm-7">
+    {{v}}
+  </div>
+</div>

data/lib/api_browser/app/views/directives/attribute_table_row/_struct.html

@@ -0,0 +1,2 @@
+<ng-include src="'views/directives/attribute_table_row/_default.html'" no-container></ng-include>
+<rs-attribute-table-row ng-repeat="(k,v) in attribute.type.attributes" name="name + '.' + k" attribute="v"></rs-attribute-table-row>

data/lib/api_browser/app/views/directives/request_body/_default.html

@@ -0,0 +1,20 @@
+<div class="attribute-table">
+  <div class="row head">
+    <div class="col-sm-3">
+      Type
+    </div>
+    <div class="col-sm-9">
+      Type Attributes
+    </div>
+  </div>
+  <div class="content">
+  <div class="row head">
+    <div class="col-sm-3">
+      {{payload.type.name}}
+    </div>
+    <div class="col-sm-9">
+      <rs-attribute-description attribute="{options:{example:payload.example,typeData:payload.type}}"></rs-attribute-description>
+    </div>
+  </div>
+  </div>
+</div>

data/lib/api_browser/app/views/directives/request_body/_struct.html

@@ -0,0 +1 @@
+<rs-attribute-table attributes="attributes" show-groups="true"></rs-attribute-table>

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

@@ -0,0 +1,7 @@
+<!-- Home -->
+
+<div class="jumbotron">
+  <h2>
+    API Doc Browser
+  </h2>
+</div>

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

@@ -0,0 +1,50 @@
+<!-- layout -->
+
+<div class="header">
+  <div class="navbar navbar-default navbar-fixed-top" role="navigation">
+    <div class="container">
+      <div class="navbar-header">
+        <a class="navbar-brand" href="#">API Browser</a>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div class="container" ng-cloak>
+  <div class="row">
+    <div class="col-sm-3" ng-controller="MenuCtrl">
+      <div class="sidebar affix">
+        <div class="row">
+          <div class="col-sm-12">
+            <p>
+              <div class="btn-group" dropdown is-open="status.isopen">
+                <button type="button" class="btn btn-success dropdown-toggle" ng-disabled="disabled">
+                  API Version: {{selectedVersion}} <span class="caret"></span>
+                </button>
+                <ul class="dropdown-menu col-sm-12" role="menu">
+                  <li ng-repeat="version in versions">
+                    <a ng-click="select(version)" dropdown-toggle>{{version}}</a>
+                  </li>
+                </ul>
+              </div>
+            </p>
+          </div>
+        </div>
+        <div class="row">
+          <div class="col-sm-12">
+            <div class="list-group">
+              <a ng-repeat="link in availableLinks()"
+                 href="{{link.stateRef}}"
+                 class="list-group-item"
+                 ng-class="{active: link.typeName == currentType}">
+                {{ link.name }}
+              </a>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+    <div class="col-sm-9" ui-view="">
+    </div>
+  </div>
+</div>

data/lib/api_browser/app/views/resource/_actions.html

@@ -0,0 +1,23 @@
+<div class="attribute-table">
+  <div class="row head">
+    <div class="col-sm-3">
+      Name
+    </div>
+    <div class="col-sm-9">
+      Description
+    </div>
+  </div>
+  <div class="content">
+    <div class="row" ng-repeat="action in controller.actions">
+      <div class="col-sm-3">
+        <a ui-sref="root.action({action: action.name, controller: controllerName, version: apiVersion})">{{ action.name }}</a>
+      </div>
+      <div class="col-sm-9">
+        <div ng-repeat="url in action.urls">
+          {{ url.verb }} {{ url.path }}
+        </div>
+        {{ action.description }}
+      </div>
+    </div>
+  </div>
+</div>

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

@@ -0,0 +1,29 @@
+<div class="row" ng-if="type">
+  <div class="col-lg-12">
+    <h2>Media Type</h2>
+    <p ng-if="type.identifier"><b>Identifier: {{ type.identifier }}</b></p>
+    <p ng-if="type.description">{{type.description}}</p>
+    <rs-attribute-table attributes="type.attributes"></rs-attribute-table>
+  </div>
+</div>
+<div class="row" ng-if="views.length">
+  <div class="col-lg-12">
+    <h3>Available views</h3>
+    <tabset>
+      <tab ng-repeat="view in views" heading="{{view.name}}">
+        <div class="row">
+          <div class="col-md-4">
+            <h4>Attributes</h4>
+            <ul>
+              <li ng-repeat="(name,value) in view.attributes">{{name}}</li>
+            </ul>
+          </div>
+          <div class="col-md-8">
+            <h4>Example</h4>
+            <pre>{{view.example | friendlyJson}}</pre>
+          </div>
+        </div>
+      </tab>
+    </tabset>
+  </div>
+</div>

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

@@ -0,0 +1,25 @@
+<!-- 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>
+        {{ typeName | resourceName }}
+      </h1>
+    </div>
+  </div>
+  <div class="row" ng-if="controllers">
+    <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.controller})">{{ controller.controller | resourceName }}</a>
+        </li>
+      </ul>
+    </div>
+  </div>
+  <ng-include src="'views/type/_details.html'" />
+</div>

data/lib/api_browser/bower.json

@@ -0,0 +1,26 @@
+{
+  "name": "api_doc_browser",
+  "version": "0.0.0",
+  "authors": [
+    "Euge Gimelberg <eugene@rightscale.com>"
+  ],
+  "license": "MIT",
+  "private": true,
+  "ignore": [
+    "**/.*",
+    "node_modules",
+    "bower_components",
+    "app/bower_components",
+    "test",
+    "tests"
+  ],
+  "dependencies": {
+    "angular": "~1.2.6",
+    "jquery": "2.1.1",
+    "lodash": "~2.4.1",
+    "bootstrap-sass": "~3.0.2",
+    "angular-ui-router": "~0.2.10",
+    "angular-ui-bootstrap-bower": "~0.11.0",
+    "angular-sanitize": "~1.2.16"
+  }
+}

data/lib/api_browser/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "api_doc_browser",
+  "version": "0.0.0",
+  "description": "",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "BSD",
+  "devDependencies": {
+    "grunt": "~0.4.2",
+    "grunt-angular-templates": "^0.5.5",
+    "grunt-contrib-clean": "^0.5.0",
+    "grunt-contrib-concat": "^0.4.0",
+    "grunt-contrib-connect": "^0.7.1",
+    "grunt-contrib-copy": "^0.5.0",
+    "grunt-contrib-cssmin": "^0.9.0",
+    "grunt-contrib-uglify": "^0.4.0",
+    "grunt-contrib-watch": "~0.5.3",
+    "grunt-file-blocks": "^0.3.0",
+    "grunt-filerev": "^0.2.1",
+    "grunt-ngmin": "0.0.3",
+    "grunt-sass": "^0.12.1",
+    "grunt-usemin": "^2.1.1",
+    "grunt-wiredep": "^1.7.0",
+    "load-grunt-tasks": "^0.4.0",
+    "requirejs": "^2.1.13",
+    "time-grunt": "^0.3.1"
+  }
+}

data/lib/praxis/action_definition/headers_dsl_compiler.rb

@@ -0,0 +1,36 @@
+module Praxis
+  class ActionDefinition
+    class HeadersDSLCompiler < Attributor::DSLCompiler
+
+      alias_method :orig_attribute, :attribute
+      # it allows to define expectations on incoming headers. For example:
+      # header :X_SpecialCookie                        => implies the header is required
+      # header :X_Something, /matching_this/           => implies that if the name header exists, it should match the regexp
+      # header :X_A_Header, "Specific String"          => implies that the value matches the string exactly
+      # In any of the cases, other supported options might be passed
+      # header :X_Something, /matching_this/ ,
+      #                     required: true             => to make it required
+      #                     description: "lorem ipsum" => to describe it (like any other attribute)
+
+      def header(name, val=nil, **options )
+        case val
+        when Regexp
+          options[:regexp] = val
+        when String
+          options[:values] = [val]
+        when nil
+          # Defining the existence without any other options can only mean that it is required (otherwise it is a useless definition)
+          options[:required] = true if options.empty?
+        end
+        orig_attribute name.upcase , String, options
+      end
+
+      def attribute( name, type, **rest)
+        raise Exceptions::InvalidConfiguration.new(
+          "You cannot use the 'attribute' DSL inside a headers definition"
+        )
+      end
+
+    end
+  end
+end

data/lib/praxis/action_definition.rb

@@ -0,0 +1,153 @@
+# A RESTful action allows you to define the following:
+# - a payload structure
+# - a params structure
+# - the response MIME type
+# - the return code/s ?
+#
+# Plugins may be used to extend this Config DSL.
+#
+module Praxis
+  class ActionDefinition
+
+    attr_reader :name
+    attr_reader :resource_definition
+    attr_reader :routes
+    attr_reader :primary_route
+    attr_reader :named_routes
+    attr_reader :responses
+
+
+    def initialize(name, resource_definition, **opts, &block)
+      @name = name
+      @resource_definition = resource_definition
+      @responses = Hash.new
+
+      if (media_type = resource_definition.media_type)
+        if media_type.kind_of?(Class) && media_type < Praxis::MediaType
+          @reference_media_type = media_type
+        end
+      end
+
+      if resource_definition.params
+        saved_type, saved_opts, saved_block = resource_definition.params
+        params(saved_type, saved_opts, &saved_block)
+      end
+
+      if resource_definition.payload
+        saved_type, saved_opts, saved_block = resource_definition.payload
+        payload(saved_type, saved_opts, &saved_block)
+      end
+
+      if resource_definition.headers
+        saved_opts, saved_block = resource_definition.headers
+        headers(saved_opts, &saved_block)
+      end
+
+      resource_definition.responses.each do |name, args|
+        response(name, args)
+      end
+
+      self.instance_eval(&block) if block_given?
+    end
+
+    def update_attribute(attribute, options, block)
+      attribute.options.merge!(options)
+      attribute.type.attributes(options, &block)
+    end
+
+    def response( name, **args )
+      template = ApiDefinition.instance.response(name)
+      @responses[name] = template.compile(self, **args)
+    end
+
+    def create_attribute(type=Attributor::Struct, **opts, &block)
+      unless opts[:reference]
+        opts[:reference] = @reference_media_type if @reference_media_type && block
+      end
+
+      return Attributor::Attribute.new(type, opts, &block)
+    end
+
+    def use(trait_name)
+      unless ApiDefinition.instance.traits.has_key? trait_name
+        raise Exceptions::InvalidTrait.new("Trait #{trait_name} not found in the system")
+      end
+      self.instance_eval(&ApiDefinition.instance.traits[trait_name])
+    end
+
+    def params(type=Attributor::Struct, **opts, &block)
+      return @params if !block && type == Attributor::Struct
+
+      if @params
+        unless type == Attributor::Struct && @params.type < Attributor::Struct
+          raise Exceptions::InvalidConfiguration.new(
+            "Invalid type received for extending params: #{type.name}"
+          )
+        end
+        update_attribute(@params, opts, block)
+      else
+        @params = create_attribute(type, **opts, &block)
+      end
+    end
+
+    def payload(type=Attributor::Struct, **opts, &block)
+      return @payload if !block && type == Attributor::Struct
+
+      if @payload
+        unless type == Attributor::Struct && @payload.type < Attributor::Struct
+          raise Exceptions::InvalidConfiguration.new(
+            "Invalid type received for extending params: #{type.name}"
+          )
+        end
+        update_attribute(@payload, opts, block)
+      else
+        @payload = create_attribute(type, **opts, &block)
+      end
+    end
+
+    def headers(**opts, &block)
+      return @headers unless block
+
+      if @headers
+        update_attribute(@headers, opts, block)
+      else
+        @headers = create_attribute(dsl_compiler: HeadersDSLCompiler, **opts, &block)
+      end
+    end
+
+    def routing(&block)
+      routing_config = Skeletor::RestfulRoutingConfig.new(name, resource_definition, &block)
+
+      @routes = routing_config.routes
+      @primary_route = routing_config.routes.first
+      @named_routes = routing_config.routes.each_with_object({}) do |route, hash|
+        next if route.name.nil?
+        hash[route.name] = route
+      end
+    end
+
+    def description(text = nil)
+      @description = text if text
+      @description
+    end
+
+
+
+    def describe
+      {}.tap do |hash|
+        hash[:description] = description
+        hash[:name] = name
+        # FIXME: change to :routes along with api browser
+        hash[:urls] = routes.collect(&:describe)
+        hash[:headers] = headers.describe if headers
+        hash[:params] = params.describe if params
+        hash[:payload] = payload.describe if payload
+        hash[:responses] = responses.inject({}) do |memo, (response_name, response)|
+          memo[response.name] = response.describe
+          memo
+        end
+      end
+    end
+
+  end
+end

data/lib/praxis/api_definition.rb

@@ -0,0 +1,59 @@
+require 'singleton'
+require 'forwardable'
+
+module Praxis
+
+  class ApiDefinition
+    include Singleton
+    extend Forwardable
+
+    attr_reader :traits
+    attr_reader :responses
+
+    def self.define(&block)
+      if block.arity == 0
+        self.instance.instance_eval(&block)
+      else
+        yield(self.instance)
+      end
+    end
+
+
+    def initialize
+      @responses = Hash.new
+      @traits = Hash.new
+    end
+
+    def response_template(name, &block)
+      @responses[name] = Praxis::ResponseTemplate.new(name, &block)
+    end
+
+    def response(name)
+      return @responses.fetch(name) do
+        raise ArgumentError, "no response defined with name #{name.inspect}"
+      end
+    end
+
+    def trait(name, &block)
+      if self.traits.has_key? name
+        raise Exceptions::InvalidTrait.new("Overwriting a previous trait with the same name (#{name})")
+      end
+      self.traits[name] = block
+    end
+
+
+    define do |api|
+      api.response_template :ok do |media_type: |
+        media_type media_type
+        status 200
+      end
+
+      api.response_template :created do |media_type: |
+        media_type media_type
+        status 201
+      end
+    end
+
+  end
+
+end