praxis 0.17.1 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bff7fa716d64ecf217102ec4c36cb53c052621ab
-  data.tar.gz: 372c8c5e252e0bff274a3c0d5f105d16deb515cc
+  metadata.gz: 5c55f5d3363aed4bc5157e0064e35b399e1bcf20
+  data.tar.gz: 2bf66b28b0d80ea8e57de43b69dc5c76e7e504ea
 SHA512:
-  metadata.gz: d2c4326ada2a6b7bc8b72ab28ca0cd87ee945a8086f096511accd18585d060f7304bc06649ed9abbff3d970e912960e069f8ec73e4ef0888140ca075fc8568ac
-  data.tar.gz: f59b8ce34535a3294523f947abcda452b6b587c31c31a0a7c02c1cf19bb4a826c1cfbce37cd092cbe137900c0b8fc539761eefd62ca1e679ea0721a842101bf1
+  metadata.gz: 32fdd9a038fa46b129d1da10a9edee94d032c2ff7ce14889cf45f162b57e3d2aaf4d3ecc4f5827ddb84a2bc33490259293a4b84a3905cd2dd269f1fb0a2a29c2
+  data.tar.gz: 04b7c664a294d7766e65640855112fb80455f6ba3fe7c840bb5b70e5de4d8bcf13b58f8cefaf151ea3787644185c4e20070f5f5cb2edcf2c58d78822ca2fef63

data/.travis.yml

@@ -1,5 +1,6 @@
 language: ruby
 cache: bundler
+sudo: false
 rvm:
   - 2.1.5
   - 2.2.2

data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## next
 
+## 0.18.0
+
+* Added `display_name` DSL to `ResourceDefinition` and `MediaType`
+  * It is a purely informational field, mostly to be used by consumers of the generated docs
+  * It defaults to the class name (stripping any of the prefix modules)
+* Revamped document generation to output a more compact format:
+    * 1 file per api version: including info, resources, schemas and traits.
+    * 1 single index file with global info plus just a list of version names
+    * new task currently usable through `bundle exec rake praxis:docs:generate_beta`
+      * NOTE: leaves the current doc generation tasks and code intact (until the doc browser is switched to use this)
+* Specialized `Multipart`’s family in its description to be ‘multipart’ instead of ‘hash’.
+* Added `Praxis::Handlers::FormData` for 'multipart/form-data'. Currently returns the input unchanged in `parse` and `generate`.
+* Added `Praxis::Handlers::WWWForm` for form-encoded data.
+* Added `Docs::Generator`, experimental new documentation generator. Use the `praxis:docs:experiments` rake task to generate. *Note*: not currently compatible with the documentation browser.
+* Added 'praxis.request_stage.execute' `ActiveSupport::Notifications` instrumentation to contorller action method execution in `RequestStages::Action#execute`.
+* Make action headers, params and payloads be required by default as it is probably what most people expect from it. To make any of those three definitions non-required, simply add the `:required` option as used in any other attribute definition. For example: `payload required: false do ...`
+
 ## 0.17.1
 
 * Fixes an issue that would make exported documentation broken.
@@ -47,6 +64,7 @@ config option, and uses the `media_type` defined for the response definition.
 * Adds hierarchival navigation to the doc browser.
 * Adds a ConfigurationProvider allowing for easy doc customization.
 
+
 ## 0.16.1
 
 * Fixed a bug where documentation generation would fail if an application had headers in a Trait using the simplified `header` DSL.

data/lib/api_browser/package.json

@@ -23,7 +23,7 @@
     "grunt-file-blocks": "^0.3.0",
     "grunt-filerev": "^0.2.1",
     "grunt-ng-annotate": "^0.10.0",
-    "grunt-sass": "^0.18.0",
+    "grunt-sass": "^1.0.0",
     "grunt-usemin": "^2.1.1",
     "grunt-wiredep": "^1.7.0",
     "load-grunt-tasks": "^0.4.0"

data/lib/praxis/action_definition.rb

@@ -67,7 +67,7 @@ module Praxis
       unless ApiDefinition.instance.traits.has_key? trait_name
         raise Exceptions::InvalidTrait.new("Trait #{trait_name} not found in the system")
       end
-      
+
       trait = ApiDefinition.instance.traits.fetch(trait_name)
       trait.apply!(self)
       traits << trait_name
@@ -82,7 +82,7 @@ module Praxis
     def response(name, type=nil, **args, &block)
       if type
         # should verify type is a media type
-        
+
         if block_given?
           type = type.construct(block)
         end
@@ -103,7 +103,11 @@ module Praxis
     end
 
     def params(type=Attributor::Struct, **opts, &block)
-      return @params if !block && type == Attributor::Struct
+      return @params if !block && ( opts.nil? || opts.empty? ) && type == Attributor::Struct
+
+      unless( opts.key? :required )
+        opts[:required] = true # Make the payload required by default
+      end
 
       if @params
         unless type == Attributor::Struct && @params.type < Attributor::Struct
@@ -128,7 +132,11 @@ module Praxis
     end
 
     def payload(type=Attributor::Struct, **opts, &block)
-      return @payload if !block && type == Attributor::Struct
+      return @payload if !block && ( opts.nil? || opts.empty? ) && type == Attributor::Struct
+
+      unless( opts.key? :required )
+        opts[:required] = true # Make the payload required by default
+      end
 
       if @payload
         unless type == Attributor::Struct && @payload.type < Attributor::Struct
@@ -144,6 +152,11 @@ module Praxis
 
     def headers(type=nil, **opts, &block)
       return @headers unless block
+
+      unless( opts.key? :required )
+        opts[:required] = true # Make the payload required by default
+      end
+
       if @headers
         update_attribute(@headers, opts, block)
       else
@@ -188,32 +201,56 @@ module Praxis
       @description
     end
 
+    def self.url_description(route:, params_example:, params:)
+      route_description = route.describe
+
+      example_hash = params_example ? params_example.dump : {}
+      hash = route.example(example_hash: example_hash, params: params)
+
+      query_string = URI.encode_www_form(hash[:query_params])
+      url = hash[:url]
+      url = [url,query_string].join('?') unless query_string.empty?
+
+      route_description[:example] = url
+      route_description
+    end
 
-    def describe
+    def describe(context: nil)
       {}.tap do |hash|
         hash[:description] = description
         hash[:name] = name
         hash[:metadata] = metadata
-        # FIXME: change to :routes along with api browser
-        hash[:urls] = routes.collect(&:describe)
-        hash[:headers] = headers.describe if headers
+        if headers
+          headers_example = headers.example(context)
+          hash[:headers] = headers.describe(example: headers_example)
+        end
         if params
-          hash[:params] = params_description
+          params_example = params.example(context)
+          hash[:params] = params_description(example: params_example)
         end
-        hash[:payload] = payload.describe if payload
+        if payload
+          payload_example = payload.example(context)
+
+          hash[:payload] = payload_description(example: payload_example)
+        end
+
         hash[:responses] = responses.inject({}) do |memo, (response_name, response)|
-          memo[response.name] = response.describe
+          memo[response.name] = response.describe(context: context)
           memo
         end
         hash[:traits] = traits if traits.any?
-
+        # FIXME: change to :routes along with api browser
+        hash[:urls] = routes.collect do |route|
+          ActionDefinition.url_description(route: route, params: self.params, params_example: params_example)
+        end.compact
         self.class.doc_decorations.each do |callback|
           callback.call(self, hash)
         end
       end
     end
 
-    def params_description
+
+    def params_description(example:)
       route_params = []
       if primary_route.nil?
         warn "Warning: No routes defined for #{resource_definition.name}##{name}."
@@ -224,7 +261,7 @@ module Praxis
           collect(&:to_sym)
       end
 
-      desc = params.describe
+      desc = params.describe(example: example)
       desc[:type][:attributes].keys.each do |k|
         source = if route_params.include? k
           'url'
@@ -236,6 +273,74 @@ module Praxis
       desc
     end
 
+    # Determine the content_type to report for a given example,
+    # using handler_name if possible.
+    #
+    # Considers any pre-defined set of values on the content_type attributge
+    # of the headers.
+    def derive_content_type(example, handler_name)
+      # MultipartArrays *must* use the provided content_type
+      if example.kind_of? Praxis::Types::MultipartArray
+        return MediaTypeIdentifier.load(example.content_type)
+      end
+
+       _, content_type_attribute = self.headers && self.headers.attributes.find { |k,v| k.to_s =~ /^content[-_]{1}type$/i }
+      if content_type_attribute && content_type_attribute.options.key?(:values)
+
+        # if any defined value match the preferred handler_name, return it
+        content_type_attribute.options[:values].each do |ct|
+          mti = MediaTypeIdentifier.load(ct)
+          return mti if mti.handler_name == handler_name
+        end
+
+        # otherwise, pick the first
+        pick = MediaTypeIdentifier.load(content_type_attribute.options[:values].first)
+
+        # and return that one if it already corresponds to a registered handler
+        # otherwise, add the encoding
+        if Praxis::Application.instance.handlers.include?(pick.handler_name)
+          return pick
+        else
+          return pick + handler_name
+        end
+      end
+
+      # generic default encoding
+      MediaTypeIdentifier.load("application/#{handler_name}")
+    end
+
+
+    def payload_description(example:)
+      hash = payload.describe(example: example)
+
+      hash[:examples] = {}
+
+      default_handlers = ApiDefinition.instance.info.consumes
+
+      default_handlers.each do |default_handler|
+        dumped_payload = payload.dump(example, default_format: default_handler)
+
+        content_type = derive_content_type(example, default_handler)
+        handler = Praxis::Application.instance.handlers[content_type.handler_name]
+
+        # in case handler is nil, use dumped_payload as-is.
+        generated_payload = if handler.nil?
+          dumped_payload
+        else
+          handler.generate(dumped_payload)
+        end
+
+
+        hash[:examples][default_handler] = {
+          content_type: content_type.to_s,
+          body: generated_payload
+        }
+      end
+
+      hash
+    end
+
+
     def nodoc!
       metadata[:doc_visibility] = :none
     end

data/lib/praxis/api_general_info.rb

@@ -10,8 +10,9 @@ module Praxis
 
       if @global_info.nil? # this *is* the global info
         version_with [:header, :params]
+        consumes 'json', 'x-www-form-urlencoded'
+        produces 'json'
       end
-
     end
 
     def get(k)
@@ -97,6 +98,24 @@ module Praxis
       end
     end
 
+    def consumes(*vals)
+      if vals.empty?
+        return get(:consumes)
+      else
+        return set(:consumes, vals)
+      end
+    end
+
+
+    def produces(*vals)
+      if vals.empty?
+        return get(:produces)
+      else
+        return set(:produces, vals)
+      end
+    end
+
+
     def base_params(type=Attributor::Struct, **opts, &block)
       if !block && type == Attributor::Struct
         get(:base_params)
@@ -105,10 +124,9 @@ module Praxis
       end
     end
 
-
     def describe
       hash = { schema_version: "1.0".freeze }
-      [:name, :title, :description, :base_path, :version_with, :endpoint].each do |attr|
+      [:name, :title, :description, :base_path, :version_with, :endpoint, :consumes, :produces].each do |attr|
         val = self.__send__(attr)
         hash[attr] = val unless val.nil?
       end

data/lib/praxis/application.rb

@@ -93,6 +93,7 @@ module Praxis
     #
     # @param [String] name
     # @param [Class] a class that responds to .new, #parse and #generate
+
     def handler(name, handler)
       # Construct an instance, if the handler is a class and needs to be initialized.
       handler = handler.new

data/lib/praxis/dispatcher.rb

@@ -79,25 +79,27 @@ module Praxis
       payload = {request: request, response: nil}
 
       Notifications.instrument 'praxis.request.all'.freeze, payload do
-        # the response stage must be the final stage in the list
-        *stages, response_stage = @stages
-        
-        stages.each do |stage|
-          result = stage.run
-          case result
-          when Response
-            controller.response = result
-            break
+        begin
+          # the response stage must be the final stage in the list
+          *stages, response_stage = @stages
+
+          stages.each do |stage|
+            result = stage.run
+            case result
+            when Response
+              controller.response = result
+              break
+            end
           end
-        end
 
-        response_stage.run
+          response_stage.run
 
-        payload[:response] = controller.response
-        controller.response.finish
+          payload[:response] = controller.response
+          controller.response.finish
+        rescue => e
+          @application.error_handler.handle!(request, e)
+        end
       end
-    rescue => e
-      @application.error_handler.handle!(request, e)
     ensure
       @controller = nil
       @action = nil
@@ -105,6 +107,7 @@ module Praxis
     end
 
 
+    # TODO: fix for multithreaded environments
     def reset_cache!
       return unless Praxis::Blueprint.caching_enabled?
 

data/lib/praxis/docs/generator.rb

@@ -0,0 +1,208 @@
+module Praxis
+  module Docs
+
+    class Generator
+      API_DOCS_DIRNAME = 'docs/api'
+
+      attr_reader :resources_by_version, :types_by_id, :infos_by_version
+      attr_reader :doc_root_dir
+
+      EXCLUDED_TYPES_FROM_OUTPUT = Set.new([
+        Attributor::Boolean,
+        Attributor::CSV,
+        Attributor::DateTime,
+        Attributor::Float,
+        Attributor::Hash,
+        Attributor::Ids,
+        Attributor::Integer,
+        Attributor::Object,
+        Attributor::String,
+        Attributor::Symbol
+      ]).freeze
+
+
+      def initialize(root)
+        require 'yaml'
+        @resources_by_version =  Hash.new do |h,k|
+          h[k] = Set.new
+        end
+        initialize_directories(root)
+
+        Attributor::AttributeResolver.current = Attributor::AttributeResolver.new
+        collect_infos
+        collect_resources
+        collect_types
+      end
+
+      def save!
+        write_index_file
+        resources_by_version.keys.each do |version|
+          write_version_file(version)
+        end
+      end
+
+      private
+
+      def initialize_directories(root)
+        @doc_root_dir = File.join(root, API_DOCS_DIRNAME)
+
+        # remove previous data (and reset the directory)
+        FileUtils.rm_rf @doc_root_dir if File.exists?(@doc_root_dir)
+        FileUtils.mkdir_p @doc_root_dir unless File.exists? @doc_root_dir
+      end
+
+      def collect_resources
+        # load all resource definitions registered with Praxis
+        Praxis::Application.instance.resource_definitions.map do |resource|
+          # skip resources with doc_visibility of :none
+          next if resource.metadata[:doc_visibility] == :none
+          version = resource.version
+          # TODO: it seems that we shouldn't hardcode n/a in Praxis
+          #  version = "unversioned" if version == "n/a"
+          @resources_by_version[version] << resource
+        end
+      end
+
+      def collect_types
+        @types_by_id = ObjectSpace.each_object( Class ).select do |obj|
+          obj < Attributor::Type
+        end.index_by(&:id)
+      end
+
+      def collect_infos
+        # All infos. Including keys for `:global`, "n/a", and any string version
+        @infos_by_version = ApiDefinition.instance.describe
+      end
+
+
+      # Recursively inspect the structure in data and collect any
+      # newly discovered types into the `reachable_types` in/out parameter
+      def collect_reachable_types( data, reachable_types )
+        case data
+        when Array
+          data.collect{|item| collect_reachable_types( item , reachable_types) }
+        when Hash
+          if data.key?(:type) && data[:type].kind_of?(Hash) && ( [:id,:name,:family] - data[:type].keys ).empty?
+            type_id = data[:type][:id]
+            unless type_id.nil?
+              unless types_by_id[type_id]
+                raise "Error! We have detected a reference to a 'Type' which is not derived from Attributor::Type" +
+                      " Document generation cannot proceed."
+              end
+              reachable_types << types_by_id[type_id]
+            end
+          end
+          data.values.map{|item| collect_reachable_types( item , reachable_types)}
+        end
+        reachable_types
+      end
+
+      def write_index_file
+        # Gather the versions
+        versions = infos_by_version.keys.reject{|v| v == :global || v == :traits }.map do |version|
+          version == "n/a" ? "unversioned" : version
+        end
+        data = {
+          info: infos_by_version[:global][:info],
+          versions: versions
+          # Note, I don't think we need to report the global traits (but rather the ones in the version)
+        }
+        filename = File.join(doc_root_dir, "index-new.json")
+        puts "Generating Index file: #{filename}"
+        File.open(filename, 'w') {|f| f.write(JSON.pretty_generate(data))}
+      end
+
+      def write_version_file( version )
+        version_info = infos_by_version[version]
+        # Hack, let's "inherit/copy" all traits of a version from the global definition
+        # Eventually traits should be defined for a version (and inheritable from global) so we'll emulate that here
+        version_info[:traits] = infos_by_version[:traits]
+        dumped_resources = dump_resources( resources_by_version[version] )
+        found_media_types =  resources_by_version[version].collect {|r| r.media_type.describe }
+
+        collected_types = Set.new
+        collect_reachable_types( dumped_resources, collected_types );
+        collect_reachable_types( found_media_types , collected_types );
+
+        dumped_schemas = dump_schemas( collected_types )
+
+        full_data = {
+          info: version_info[:info],
+          resources: dumped_resources,
+          schemas: nil,#dumped_schemas,
+          traits: version_info[:traits] || []
+        }
+        # Write the file
+        version_file = ( version == "n/a" ? "unversioned" : version )
+        filename = File.join(doc_root_dir, version_file)
+
+        puts "Generating API file: #{filename} (in json and yaml)"
+        File.open(filename+".json", 'w') {|f| f.write(JSON.pretty_generate(full_data))}
+        File.open(filename+".yml", 'w') {|f| f.write(YAML.dump(full_data))}
+      end
+
+
+      def dump_resources( resources )
+        resources.each_with_object({}) do |r, hash|
+          # Do not report undocumentable resources
+          next if r.metadata[:doc_visibility] == :none
+          context = [r.id]
+          resource_description = r.describe(context: context)
+
+          # strip actions with doc_visibility of :none
+          resource_description[:actions].reject! { |a| a[:metadata][:doc_visibility] == :none }
+
+          # Go through the params/payload of each action and augment them by
+          # adding a generated example (then stick it into the description hash)
+          r.actions.each do |action_name, action|
+            # skip actions with doc_visibility of :none
+            next if action.metadata[:doc_visibility] == :none
+
+            action_description = resource_description[:actions].find {|a| a[:name] == action_name }
+          end
+
+          hash[r.id] = resource_description
+        end
+      end
+
+
+      def dump_schemas(types)
+        reportable_types = types - EXCLUDED_TYPES_FROM_OUTPUT
+        reportable_types.each_with_object({}) do |type, array|
+          context = [type.id]
+          example_data = type.example(context)
+          type_output = type.describe(false, example: example_data)
+          unless type_output[:display_name]
+            # For non MediaTypes or pure types or anonymous types fallback to their name, and worst case to their id
+            type_output[:display_name] = type_output[:name] || type_output[:id]
+          end
+          if type_output[:views]
+            type_output[:views].delete(:master)
+            type_output[:views].each do |view_name, view_info|
+              view_info[:example] = example_data.render(view: view_name)
+            end
+          end
+          type_output[:example] = if example_data.respond_to? :render
+            example_data.render(view: :master)
+          else
+            type.dump(example_data)
+          end
+          array[type.id] = type_output
+        end
+      end
+
+
+      def dump_example_for(context_name, object)
+        example = object.example(Array(context_name))
+        if object.is_a? Praxis::Blueprint
+          example.render(view: :master)
+        elsif object.is_a? Attributor::Attribute
+          object.dump(example)
+        else
+          raise "Do not know how to dump this object (it is not a Blueprint or an Attribute): #{object}"
+        end
+      end
+
+    end
+  end
+end

data/lib/praxis/handlers/www_form.rb

@@ -13,7 +13,8 @@ module Praxis
       # Generate a URL-encoded WWW form from structured data. Not implemented since this format
       # is not very useful for a response body.
       def generate(structured_data)
-        raise NotImplementedError
+        return nil if structured_data.nil?
+        URI.encode_www_form(structured_data)
       end
     end
   end

data/lib/praxis/media_type.rb

@@ -80,7 +80,7 @@ module Praxis
         RUBY
       end
     end
-    
+
   end
 
 end