praxis 0.13.0 → 0.14.0

data/lib/praxis/restful_doc_generator.rb

@@ -6,7 +6,7 @@ module Praxis
     end
 
     @inspected_types = Set.new
-    API_DOCS_DIRNAME = 'api_docs'
+    API_DOCS_DIRNAME = 'docs/api'
 
     EXCLUDED_TYPES_FROM_TOP_LEVEL = Set.new([
       Attributor::Boolean,
@@ -81,12 +81,25 @@ module Praxis
 
           add_to_reachable RestfulDocGenerator.inspect_attributes(action_config.params)
           add_to_reachable RestfulDocGenerator.inspect_attributes(action_config.payload)
+
+          action_config.responses.values.each do |response|
+            add_to_reachable RestfulDocGenerator.inspect_attributes(response.media_type)
+          end
         end
 
       end
 
       # TODO: I think that the "id"/"name" of a resource should be provided by the definition/controller...not derived here
       def id
+        if @controller_config.controller
+          @controller_config.controller.id
+        else
+          # If an API doesn't quite have the controller defined, let's use the name from the resource definition
+          @controller_config.id
+        end
+      end
+
+      def name
         if @controller_config.controller
           @controller_config.controller.name
         else
@@ -95,6 +108,17 @@ module Praxis
         end
       end
 
+      def friendly_name
+        # FIXME: is it really about the controller? or the attached resource definition?
+        segments = self.name.split("::")
+        # FIXME: Crappy hack to derive a friendly name
+        if ["Collection","Links"].include? segments.last
+          segments[-2] + segments[-1] # concat the last 2
+        else
+          segments.last
+        end
+      end
+
       def add_to_reachable( found )
         return if found == nil
         @reachable_types += found
@@ -119,6 +143,7 @@ module Praxis
       write_resources
       write_types(types_for)
       write_index(types_for)
+      write_info(types_for)
       write_templates(types_for)
     end
 
@@ -182,7 +207,7 @@ module Praxis
         FileUtils.mkdir_p dirname unless File.exists? dirname
         reportable_types = types - EXCLUDED_TYPES_FROM_TOP_LEVEL
         reportable_types.each do |type|
-          filename = File.join(dirname, "#{type.name}.json")
+          filename = File.join(dirname, "#{type.id}.json")
           #puts "Dumping #{type.name} to #{filename}"
           type_output = type.describe
           example_data = type.example(type.to_s)
@@ -233,12 +258,12 @@ module Praxis
 
       @resources.each do |r|
         index[r.version] ||= Hash.new
-        info = {controller: r.id}
+        info = {controller: r.id, name: r.name}
         if r.media_type
-          info[:media_type] = r.media_type.name
+          info[:media_type] = r.media_type.id
           media_types_seen_from_controllers << r.media_type
         end
-        display_name  = r.id.split("::").last
+        display_name  = r.name.split("::").last
         index[r.version][display_name] = info
       end
 
@@ -255,9 +280,9 @@ module Praxis
             raise "Display name already taken for version #{version}! #{display_name}"
           end
           index[version][display_name] = if type < Praxis::MediaType
-            {media_type: type.name }
+            {media_type: type.id }
           else
-            {kind: type.name}
+            {kind: type.id}
           end
         end
       end
@@ -267,6 +292,68 @@ module Praxis
       File.open(filename, 'w') {|f| f.write(JSON.pretty_generate(index))}
     end
 
+    # Writes an "index" type file inside each version, with some higher level information about the API
+    def write_info( versioned_types )
+
+      resources_by_version = Hash.new do |hash, v|
+        hash[v] = Set.new
+      end
+      types_by_version = Hash.new do |hash, v|
+        hash[v] = Set.new
+      end
+
+      @resources.each do |r|
+        resources_by_version[r.version]  << { id: r.id, name: r.name, friendly_name: r.friendly_name}
+      end
+
+      versioned_types.each do |version, types|
+#        # Discard any mediatypes that we've already seen and processed as controller related
+        reportable_types = types - EXCLUDED_TYPES_FROM_TOP_LEVEL
+#        #TODO: think about these special cases, is it needed?
+#        reportable_types.reject!{|type| type < Praxis::Links || type < Praxis::MediaTypeCollection }
+
+        reportable_types.each do |type|
+          segments = type.name.split("::")
+          # FIXME: Crappy hack to derive a friendly name
+          friendly_name = if ["Collection","Links"].include? segments.last
+            segments[-2] + segments[-1] # concat the last 2
+          else
+            segments.last
+          end
+
+          types_by_version[version] << { id: type.id,  name: type.name, friendly_name: friendly_name}
+        end
+      end
+      ###############################
+
+      diff = resources_by_version.keys - types_by_version.keys - versioned_types.keys
+      raise "!!!!!!!! somehow we have a list of different versions from the types vs. resources seen" unless diff.empty?
+
+      infos = {}
+      versioned_types.each do |version, types|
+        infos[version] = {info:{}}
+      end
+      infos.merge!(ApiDefinition.instance.describe)
+
+      # Add resources and types list
+      versioned_types.keys.each do |v|
+
+        infos[v][:resources] = resources_by_version[v].each_with_object({}) do |element,hash|
+          hash[element[:id]] = { name: element[:name], friendly_name: element[:friendly_name] }
+        end
+        infos[v][:schemas] = types_by_version[v].each_with_object({}) do |element,hash|
+          hash[element[:id]] = {  name: element[:name], friendly_name: element[:friendly_name] }
+        end
+      end
+
+      versioned_types.each do |version, types|
+        dirname = File.join(@doc_root_dir, version)
+        filename = File.join(dirname, "version_index.json")
+        File.open(filename, 'w') {|f| f.write(JSON.pretty_generate(infos[version]))}
+      end
+    end
+
+
     def write_templates(versioned_types)
       # Calculate and write top-level (non-versioned) templates
       top_templates = write_template("")

data/lib/praxis/simple_media_type.rb

@@ -5,15 +5,8 @@ module Praxis
       self.class.name
     end
     
-    def ===(other_thing)
-      case other_thing
-      when String
-        identifier == other_thing
-      when MediaType
-        identifier == other_thing.identifier
-      else
-        raise 'can not compare'
-      end
+    def id
+      self.class.name.gsub("::",'-')
     end
 
     def describe(shallow=true)

data/lib/praxis/stage.rb

@@ -24,14 +24,13 @@ module Praxis
     end
 
     def run
-      setup!
-      setup_deferred_callbacks!
       execute_callbacks(self.before_callbacks)
       execute
       execute_callbacks(self.after_callbacks)
     end
 
     def setup!
+      setup_deferred_callbacks!
     end
 
     def setup_deferred_callbacks!
@@ -48,8 +47,6 @@ module Praxis
     end
 
     def execute
-      raise NotImplementedError, 'Subclass must implement Stage#execute' unless @stages.any?
-
       @stages.each do |stage|
         stage.run
       end

data/lib/praxis/tasks/api_docs.rb

@@ -1,30 +1,62 @@
 namespace :praxis do
-  desc "Generate API docs (JSON definitions) for a Praxis App"
-  task :api_docs => [:environment] do |t, args|
-    require 'fileutils'
 
-    Praxis::Blueprint.caching_enabled = false
-    generator = Praxis::RestfulDocGenerator.new(Dir.pwd)
-  end
+  namespace :docs do
+    path = File.expand_path(File.join(File.dirname(__FILE__), '../../api_browser'))
 
-  desc "Run API Documentation Browser"
-  task :doc_browser, [:port] => :api_docs do |t, args|
-    args.with_defaults port: 4567
+    desc "Install dependencies"
+    task :install do
+      unless system("npm install --production", chdir: path)
+        raise Exception.new("NPM Install Failed")
+      end
+
+      docs_dir = File.join(Dir.pwd, 'docs')
+      FileUtils.mkdir_p docs_dir unless File.directory? docs_dir
 
-    public_folder =  File.expand_path("../../../", __FILE__) + "/api_browser/app"
-    app = Rack::Builder.new do
-      map "/docs" do # application JSON docs
-        use Rack::Static, urls: [""], root: File.join(Dir.pwd, Praxis::RestfulDocGenerator::API_DOCS_DIRNAME)
+      # The doc browser will need to have a minimal app.js and styles.css file at the root
+      # Let's add them if the app has not overriden them
+      js_file = File.join(Dir.pwd, 'docs', 'app.js')
+      scss_file = File.join(Dir.pwd, 'docs', 'styles.scss')
+      template_directory = File.expand_path(File.join(File.dirname(__FILE__), '../../../tasks/thor/templates/generator/empty_app/docs'))
+
+      unless File.exists? js_file
+        FileUtils.cp File.join(template_directory, 'app.js'), js_file
       end
-      map "/" do # Assets mapping
-        use Rack::Static, urls: [""], root: public_folder, index: "index.html"
+      unless File.exists? scss_file
+        FileUtils.cp File.join(template_directory, 'styles.scss'), scss_file
       end
+    end
 
-      run lambda { |env| [404, {'Content-Type' => 'text/plain'}, ['Not Found']] }
+    desc "Run API Documentation Browser"
+    task :preview, [:port] => [:install, :generate]  do |t, args|      
+      doc_port = args[:port] || '9090'
+      exec({'USER_DOCS_PATH' => File.join(Dir.pwd, 'docs'), 'DOC_PORT' => doc_port}, "#{path}/node_modules/.bin/grunt serve --gruntfile '#{path}/Gruntfile.js'")
     end
 
-    
-    Rack::Server.start app: app, Port: args[:port]
+    desc "Build docs that can be shipped"
+    task :build => [:install, :generate] do
+      exec({'USER_DOCS_PATH' => File.join(Dir.pwd, 'docs')}, "#{path}/node_modules/.bin/grunt build --gruntfile '#{path}/Gruntfile.js'")
+    end
+
+    desc "Generate API docs (JSON definitions) for a Praxis App"
+    task :generate => [:environment] do |t, args|
+      require 'fileutils'
+
+      Praxis::Blueprint.caching_enabled = false
+      generator = Praxis::RestfulDocGenerator.new(Dir.pwd)
+    end
+
+  end
+
+  desc "Generate API docs (JSON definitions) for a Praxis App"
+  task :api_docs do
+    STDERR.puts "DEPRECATION: praxis:api_docs is deprecated and will be removed by 1.0. Please use praxis:docs:generate instead."
+    Rake::Task["praxis:docs:generate"].invoke
   end
-  
+
+  desc "Run API Documentation Browser"
+  task :doc_browser, [:port] do |t, args|
+    STDERR.puts "DEPRECATION: praxis:doc_browser is deprecated and will be removed by 1.0. Please use praxis:docs:preview instead. The doc browser now runs on port 9090."
+    Rake::Task["praxis:docs:preview"].invoke
+  end
+
 end

data/lib/praxis/tasks/routes.rb

@@ -4,7 +4,6 @@ namespace :praxis do
   task :routes, [:format] => [:environment] do |t, args|
     require 'terminal-table'
 
-
     table = Terminal::Table.new title: "Routes",
     headings:  [
       "Version", "Path", "Verb",
@@ -22,23 +21,28 @@ namespace :praxis do
 
         method_name = method ? "#{method.owner.name}##{method.name}" : 'n/a'
 
-        action.routes.each do |route|
-          rows << {
-            resource: resource_definition.name,
-            version: route.version,
-            verb: route.verb,
-            path: route.path,
-            action: name,
-            implementation: method_name,
-            name: route.name,
-            primary: (action.primary_route == route ? 'yes' : '')
-          }
+        row = {
+          resource: resource_definition.name,
+          action: name,
+          implementation: method_name,
+        }
+
+        if action.routes.empty?
+          warn "Warning: No routes defined for #{resource_definition.name}##{name}."
+          rows << row
+        else
+          action.routes.each do |route|
+            rows << row.merge({
+              version: route.version,
+              verb: route.verb,
+              path: route.path,
+              name: route.name,
+              primary: (action.primary_route == route ? 'yes' : '')
+            })
         end
       end
     end
-
-
-
+  end
 
     case args[:format] || "table"
     when "json"

data/lib/praxis/types/media_type_common.rb

@@ -0,0 +1,31 @@
+module Praxis
+  module Types
+
+    module MediaTypeCommon
+      extend ::ActiveSupport::Concern
+
+      module ClassMethods
+        def describe(shallow = false)
+          hash = super
+          unless shallow
+            hash.merge!(identifier: @identifier, description: @description)
+          end
+          hash
+        end
+
+        def description(text=nil)
+          @description = text if text
+          @description
+        end
+
+        def identifier(identifier=nil)
+          return @identifier unless identifier
+          # TODO: parse the string and extract things like collection , and format type?...
+          @identifier = identifier
+        end
+      end
+
+    end
+
+  end
+end

data/lib/praxis/types/multipart.rb

@@ -28,10 +28,10 @@ module Praxis
 
       super(context, options: options).each do |k,v|
         body = if v.respond_to?(:dump) && !v.kind_of?(String)
-                JSON.pretty_generate(v.dump)
-              else
-                v
-              end
+          JSON.pretty_generate(v.dump)
+        else
+          v
+        end
 
         entity = MIME::Text.new(body)
 

data/lib/praxis/version.rb

@@ -1,3 +1,3 @@
 module Praxis
-  VERSION = '0.13.0'
+  VERSION = '0.14.0'
 end

data/praxis.gemspec

@@ -25,8 +25,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'activesupport', '>= 3'
   spec.add_dependency 'mime', '~> 0'
   spec.add_dependency 'praxis-mapper', '~> 3.3'
-  spec.add_dependency 'praxis-blueprints', '~> 1.2'
-  spec.add_dependency 'attributor', '~> 2.5.0'
+  spec.add_dependency 'praxis-blueprints', '~> 1.3'
+  spec.add_dependency 'attributor', '~> 2.6.0'
   spec.add_dependency 'thor', '~> 0.18'
   spec.add_dependency 'terminal-table', '~> 1.4'
   spec.add_dependency 'harness', '~> 2'

data/spec/api_browser/factories/documentation_spec.js

@@ -0,0 +1,50 @@
+describe('Documentation service', function() {
+  var $scope, Documentation, $httpBackend;
+
+  beforeEach(angular.mock.module('PraxisDocBrowser'));
+
+  beforeEach(inject(function($rootScope, $injector) {
+    $scope = $rootScope.$new();
+    Documentation = $injector.get('Documentation');
+    $httpBackend = $injector.get('$httpBackend');
+  }));
+
+  afterEach(function() {
+    $httpBackend.verifyNoOutstandingExpectation();
+    $httpBackend.verifyNoOutstandingRequest();
+  });
+
+  describe('#getIndex', function() {
+    var result, response = {
+      '1.0': {
+        'Blogs': {
+          'controller': 'V1-Controllers-Blogs',
+          'name': 'V1::Controllers::Blogs',
+          'media_type': 'V1-MediaTypes-Blog'
+        },
+        'Posts': {
+          'controller': 'V1-ResourceDefinitions-Posts',
+          'name': 'V1::ResourceDefinitions::Posts',
+          'media_type': 'V1-MediaTypes-Post'
+        },
+        'Users': {
+          'controller': 'V1-ResourceDefinitions-Users',
+          'name': 'V1::ResourceDefinitions::Users',
+          'media_type': 'V1-MediaTypes-User'
+        }
+      }
+    };
+    beforeEach(function() {
+      $httpBackend.expectGET('api/index.json').respond(response);
+      Documentation.getIndex().then(function(data) {
+        result = data;
+      });
+      $httpBackend.flush();
+      $scope.$apply();
+    });
+
+    it('returns the index data', function() {
+      expect(result.data).toEqual(response);
+    });
+  });
+});