apipie-rails 0.2.6 → 0.3.0

data/app/views/apipie/apipies/_disqus.html.erb

@@ -3,7 +3,7 @@
     var disqus_shortname = "<%= Apipie.configuration.disqus_shortname %>";
     (function() {
         var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
-        dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
+        dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
         (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
     })();
 </script>

data/app/views/apipie/apipies/_params.html.erb

@@ -17,7 +17,7 @@
       <%= param[:description].html_safe %>
       <% unless param[:validator].blank? %>
         <br>
-        Value: <%= param[:validator] %>
+        Value: <%= Apipie.markup_to_html(param[:validator]).html_safe %>
       <% end %>
 
       <% unless param[:metadata].blank? %>

data/app/views/apipie/apipies/_params_plain.html.erb

@@ -10,7 +10,7 @@
         <%= param[:required] ? t('apipie.required') : t('apipie.optional') %>
         <%= param[:allow_nil] ? ', '+t('apipie.nil_allowed') : '' %>
         <% if param[:validator] %>
-          [ <%= param[:validator] %> ]
+          [ <%= Apipie.markup_to_html(param[:validator]).html_safe %> ]
         <% end %>
       </small>
       <%= param[:description].html_safe %>

data/lib/apipie/application.rb

@@ -1,4 +1,5 @@
 require 'apipie/static_dispatcher'
+require 'apipie/routes_formatter'
 require 'yaml'
 require 'digest/md5'
 require 'json'
@@ -6,7 +7,6 @@ require 'json'
 module Apipie
 
   class Application
-
     # we need engine just for serving static assets
     class Engine < Rails::Engine
       initializer "static assets" do |app|
@@ -29,6 +29,49 @@ module Apipie
       @controller_to_resource_id[controller] = resource_id
     end
 
+    def rails_routes(route_set = nil)
+      if route_set.nil? && @rails_routes
+        return @rails_routes
+      end
+      route_set ||= Rails.application.routes
+      # ensure routes are loaded
+      Rails.application.reload_routes! unless Rails.application.routes.routes.any?
+
+      flatten_routes = []
+
+      route_set.routes.each do |route|
+        if route.app.respond_to?(:routes) && route.app.routes.is_a?(ActionDispatch::Routing::RouteSet)
+          # recursively go though the moutned engines
+          flatten_routes.concat(rails_routes(route.app.routes))
+        else
+          flatten_routes << route
+        end
+      end
+
+      @rails_routes = flatten_routes
+    end
+
+    # the app might be nested when using contraints, namespaces etc.
+    # this method does in depth search for the route controller
+    def route_app_controller(app, route)
+      if app.respond_to?(:controller)
+        return app.controller(route.defaults)
+      elsif app.respond_to?(:app)
+        return route_app_controller(app.app, route)
+      end
+    rescue ActionController::RoutingError
+      # some errors in the routes will not stop us here: just ignoring
+    end
+
+    def routes_for_action(controller, method, args)
+      routes = rails_routes.select do |route|
+        controller == route_app_controller(route.app, route) &&
+            method.to_s == route.defaults[:action]
+      end
+
+      Apipie.configuration.routes_formatter.format_routes(routes, args)
+    end
+
     # create new method api description
     def define_method_description(controller, method_name, dsl_data)
       return if ignored?(controller, method_name)

data/lib/apipie/configuration.rb

@@ -4,9 +4,10 @@ module Apipie
     attr_accessor :app_name, :app_info, :copyright, :markup, :disqus_shortname,
       :api_base_url, :doc_base_url, :required_by_default, :layout,
       :default_version, :debug, :version_in_url, :namespaced_resources,
-      :validate, :validate_value, :validate_presence, :authenticate, :doc_path,
+      :validate, :validate_value, :validate_presence, :validate_key, :authenticate, :doc_path,
       :show_all_examples, :process_params, :update_checksum, :checksum_path,
-      :link_extension, :record, :languages, :translate, :locale, :default_locale
+      :link_extension, :record, :languages, :translate, :locale, :default_locale,
+      :persist_show_in_doc
 
     alias_method :validate?, :validate
     alias_method :required_by_default?, :required_by_default
@@ -27,6 +28,12 @@ module Apipie
     # Api::Engine.routes
     attr_accessor :api_routes
 
+    # a object responsible for transforming the routes loaded from Rails to a form
+    # to be used in the documentation, when using the `api!` keyword. By default,
+    # it's Apipie::RoutesFormatter. To customize the behaviour, one can inherit from
+    # from this class and override the methods as needed.
+    attr_accessor :routes_formatter
+
     def reload_controllers?
       @reload_controllers = Rails.env.development? unless defined? @reload_controllers
       return @reload_controllers && @api_controllers_matcher
@@ -42,6 +49,11 @@ module Apipie
     end
     alias_method :validate_presence?, :validate_presence
 
+    def validate_key
+      return (validate? && @validate_key)
+    end
+    alias_method :validate_key?, :validate_key
+
     def process_value?
       @process_params
     end
@@ -86,6 +98,10 @@ module Apipie
       @ignored.map(&:to_s)
     end
 
+    # Persist the show_in_doc value in the examples if true. Use this if you
+    # cannot set the flag in the tests themselves (no rspec for example).
+    attr_writer :persist_show_in_doc
+
     # comment to put before docs that was generated automatically. It's used to
     # determine if the description should be overwritten next recording.
     # If you want to keep the documentation (prevent from overriding), remove
@@ -124,9 +140,10 @@ module Apipie
       @app_name = "Another API"
       @app_info = HashWithIndifferentAccess.new
       @copyright = nil
-      @validate = true
+      @validate = :implicitly
       @validate_value = true
       @validate_presence = true
+      @validate_key = false
       @required_by_default = false
       @api_base_url = HashWithIndifferentAccess.new
       @doc_base_url = "/apipie"
@@ -146,6 +163,8 @@ module Apipie
       @default_locale = 'en'
       @locale = lambda { |locale| @default_locale }
       @translate = lambda { |str, locale| str }
+      @persist_show_in_doc = false
+      @routes_formatter = RoutesFormatter.new
     end
   end
 end

data/lib/apipie/dsl_definition.rb

@@ -20,7 +20,9 @@ module Apipie
 
       def _apipie_dsl_data_init
         @_apipie_dsl_data =  {
+         :api               => false,
          :api_args          => [],
+         :api_from_routes   => nil,
          :errors            => [],
          :params            => [],
          :resouce_id        => nil,
@@ -72,16 +74,25 @@ module Apipie
         Apipie.add_param_group(self, name, &block)
       end
 
-      # Declare an api.
       #
-      # Example:
-      #   api :GET, "/resource_route", "short description",
+      #   # load paths from routes and don't provide description
+      #   api
       #
       def api(method, path, desc = nil, options={}) #:doc:
         return unless Apipie.active_dsl?
+        _apipie_dsl_data[:api] = true
         _apipie_dsl_data[:api_args] << [method, path, desc, options]
       end
 
+      #   # load paths from routes
+      #   api! "short description",
+      #
+      def api!(desc = nil, options={}) #:doc:
+        return unless Apipie.active_dsl?
+        _apipie_dsl_data[:api] = true
+        _apipie_dsl_data[:api_from_routes] = { :desc => desc, :options =>options }
+      end
+
       # Reference other similar method
       #
       #   api :PUT, '/articles/:id'
@@ -189,44 +200,72 @@ module Apipie
       end
 
       def _apipie_define_validators(description)
-        # redefine method only if validation is turned on
-        if description && Apipie.configuration.validate == true
 
-          old_method = instance_method(description.method)
+        # [re]define method only if validation is turned on
+        if description && (Apipie.configuration.validate == true ||
+                           Apipie.configuration.validate == :implicitly ||
+                           Apipie.configuration.validate == :explicitly)
 
+          _apipie_save_method_params(description.method, description.params)
 
-          # @todo we should use before_filter
-          define_method(description.method) do |*args|
+          unless instance_methods.include?(:apipie_validations)
+            define_method(:apipie_validations) do
+              method_params = self.class._apipie_get_method_params(action_name)
 
-            if Apipie.configuration.validate_presence?
-              description.params.each do |_, param|
-                # check if required parameters are present
-                raise ParamMissing.new(param.name) if param.required && !params.has_key?(param.name)
+              if Apipie.configuration.validate_presence?
+                method_params.each do |_, param|
+                  # check if required parameters are present
+                  raise ParamMissing.new(param.name) if param.required && !params.has_key?(param.name)
+                end
               end
-            end
 
-            if Apipie.configuration.validate_value?
-              description.params.each do |_, param|
-                # params validations
-                param.validate(params[:"#{param.name}"]) if params.has_key?(param.name)
+              if Apipie.configuration.validate_value?
+                method_params.each do |_, param|
+                  # params validations
+                  param.validate(params[:"#{param.name}"]) if params.has_key?(param.name)
+                end
               end
-            end
 
-            if Apipie.configuration.process_value?
-              @api_params = {}
+              # Only allow params passed in that are defined keys in the api
+              # Auto skip the default params (format, controller, action)
+              if Apipie.configuration.validate_key?
+                params.reject{|k,_| %w[format controller action].include?(k.to_s) }.each_key do |param|
+                  # params allowed
+                  raise UnknownParam.new(param) if method_params.select {|_,p| p.name.to_s == param.to_s}.empty?
+                end
+              end
 
-              description.params.each do |_, param|
-                # params processing
-                @api_params[param.as] = param.process_value(params[:"#{param.name}"]) if params.has_key?(param.name)
+              if Apipie.configuration.process_value?
+                @api_params ||= {}
+                method_params.each do |_, param|
+                  # params processing
+                  @api_params[param.as] = param.process_value(params[:"#{param.name}"]) if params.has_key?(param.name)
+                end
               end
             end
+          end
+
+          if (Apipie.configuration.validate == :implicitly || Apipie.configuration.validate == true)
+            old_method = instance_method(description.method)
+
+            define_method(description.method) do |*args|
+              apipie_validations
 
-            # run the original method code
-            old_method.bind(self).call(*args)
+              # run the original method code
+              old_method.bind(self).call(*args)
+            end
           end
 
         end
+      end
 
+      def _apipie_save_method_params(method, params)
+        @method_params ||= {}
+        @method_params[method] = params
+      end
+
+      def _apipie_get_method_params(method)
+        @method_params[method]
       end
 
     end
@@ -335,22 +374,32 @@ module Apipie
       # create method api and redefine newly added method
       def method_added(method_name) #:doc:
         super
+        return if !Apipie.active_dsl? || !_apipie_dsl_data[:api]
 
-        if ! Apipie.active_dsl? || _apipie_dsl_data[:api_args].blank?
-          _apipie_dsl_data_clear
-          return
-        end
+        if _apipie_dsl_data[:api_from_routes]
+          desc = _apipie_dsl_data[:api_from_routes][:desc]
+          options = _apipie_dsl_data[:api_from_routes][:options]
 
-        begin
-          # remove method description if exists and create new one
-          Apipie.remove_method_description(self, _apipie_dsl_data[:api_versions], method_name)
-          description = Apipie.define_method_description(self, method_name, _apipie_dsl_data)
-        ensure
-          _apipie_dsl_data_clear
+          api_from_routes = Apipie.routes_for_action(self, method_name, {:desc => desc, :options => options}).map do |route_info|
+            [route_info[:verb],
+             route_info[:path],
+             route_info[:desc],
+             (route_info[:options] || {}).merge(:from_routes => true)]
+          end
+          _apipie_dsl_data[:api_args].concat(api_from_routes)
         end
 
+        return if _apipie_dsl_data[:api_args].blank?
+
+        # remove method description if exists and create new one
+        Apipie.remove_method_description(self, _apipie_dsl_data[:api_versions], method_name)
+        description = Apipie.define_method_description(self, method_name, _apipie_dsl_data)
+
+        _apipie_dsl_data_clear
         _apipie_define_validators(description)
-      end # def method_added
+      ensure
+        _apipie_dsl_data_clear
+      end
     end
 
     module Concern
@@ -381,18 +430,12 @@ module Apipie
       def method_added(method_name) #:doc:
         super
 
-        if ! Apipie.active_dsl? || _apipie_dsl_data[:api_args].blank?
-          _apipie_dsl_data_clear
-          return
-        end
-
-        begin
-          _apipie_concern_data << [method_name, _apipie_dsl_data.merge(:from_concern => true)]
-        ensure
-          _apipie_dsl_data_clear
-        end
+        return if ! Apipie.active_dsl? || !_apipie_dsl_data[:api]
 
-      end # def method_added
+        _apipie_concern_data << [method_name, _apipie_dsl_data.merge(:from_concern => true)]
+      ensure
+        _apipie_dsl_data_clear
+      end
 
     end
 

data/lib/apipie/errors.rb

@@ -21,6 +21,12 @@ module Apipie
     end
   end
 
+  class UnknownParam < DefinedParamError
+    def to_s
+      "Unknown parameter #{@param}"
+    end
+  end
+
   class ParamInvalid < DefinedParamError
     attr_accessor :value, :error
 

data/lib/apipie/extractor.rb

@@ -126,7 +126,7 @@ module Apipie
           controller = "#{controller_path}Controller"
 
           path = if /^#{Regexp.escape(@api_prefix)}(.*)$/ =~ route[:path]
-                   $1.sub!(/\(\.:format\)$/,"")
+                   $1.sub(/\(\.:format\)$/,'')
                  else
                    nil
                  end

data/lib/apipie/extractor/recorder.rb

@@ -1,6 +1,8 @@
 module Apipie
   module Extractor
     class Recorder
+      MULTIPART_BOUNDARY = 'APIPIE_RECORDER_EXAMPLE_BOUNDARY'
+
       def initialize
         @ignored_params = [:controller, :action]
       end
@@ -14,6 +16,8 @@ module Apipie
         if data = parse_data(env["rack.input"].read)
           @request_data = data
           env["rack.input"].rewind
+        elsif form_hash = env["rack.request.form_hash"]
+          @request_data = reformat_multipart_data(form_hash)
         end
       end
 
@@ -50,6 +54,37 @@ module Apipie
         data
       end
 
+      def reformat_multipart_data(form)
+        form.empty? and return ''
+        lines = ["Content-Type: multipart/form-data; boundary=#{MULTIPART_BOUNDARY}",'']
+        boundary = "--#{MULTIPART_BOUNDARY}"
+        form.each do |key, attrs|
+          if attrs.is_a?(String)
+            lines << boundary << content_disposition(key) << "Content-Length: #{attrs.size}" << '' << attrs
+          else
+            reformat_hash(boundary, attrs, lines)
+          end
+        end
+        lines << "#{boundary}--"
+        lines.join("\n")
+      end
+
+      def reformat_hash(boundary, attrs, lines)
+        if head = attrs[:head]
+          lines << boundary
+          lines.concat(head.split("\r\n"))
+          # To avoid large and/or binary file bodies, simply indicate the contents in the output.
+          lines << '' << %{... contents of "#{attrs[:name]}" ...}
+        else
+          # Look for subelements that contain a part.
+          attrs.each { |k,v| v.is_a?(Hash) and reformat_hash(boundary, v, lines) }
+        end
+      end
+
+      def content_disposition(name)
+        %{Content-Disposition: form-data; name="#{name}"}
+      end
+
       def reformat_data(data)
         parsed = parse_data(data)
         case parsed

data/lib/apipie/extractor/writer.rb

@@ -75,7 +75,7 @@ module Apipie
       def ordered_call(call)
         call = call.stringify_keys
         ordered_call = OrderedHash.new
-        %w[verb path versions query request_data response_data code show_in_doc recorded].each do |k|
+        %w[title verb path versions query request_data response_data code show_in_doc recorded].each do |k|
           next unless call.has_key?(k)
           ordered_call[k] = case call[k]
                        when ActiveSupport::HashWithIndifferentAccess
@@ -97,15 +97,37 @@ module Apipie
         merged_examples = []
         (new_examples.keys + old_examples.keys).uniq.each do |key|
           if new_examples.has_key?(key)
-            records = new_examples[key]
+            if old_examples.has_key?(key)
+              records = deep_merge_examples(new_examples[key], old_examples[key])
+            else
+              records = new_examples[key]
+            end
           else
             records = old_examples[key]
           end
-          merged_examples << [key, records.map { |r|  ordered_call(r) } ]
+          merged_examples << [key, records.map { |r| ordered_call(r) } ]
         end
         return merged_examples
       end
 
+      def deep_merge_examples(new_examples, old_examples)
+        new_examples.map do |new_example|
+          # Use ordered to get compareble output (mainly for the :query)
+          new_example_ordered = ordered_call(new_example.dup)
+
+          # Comparing verb, versions and query
+          if old_example = old_examples.find{ |old_example| old_example["verb"] == new_example_ordered["verb"] && old_example["versions"] == new_example_ordered["versions"] && old_example["query"] == new_example_ordered["query"]}
+
+            # Take the 'show in doc' attribute from the old example if it is present and the configuration requests the value to be persisted.
+            new_example[:show_in_doc] = old_example["show_in_doc"] if Apipie.configuration.persist_show_in_doc && old_example["show_in_doc"].to_i > 0
+
+            # Always take the title from the old example if it exists.
+            new_example[:title] ||= old_example["title"] if old_example["title"].present?
+          end
+          new_example
+        end 
+      end
+
       def load_new_examples
         @collector.records.reduce({}) do |h, (method, calls)|
           showed_in_versions = Set.new
@@ -272,8 +294,8 @@ module Apipie
                      "List #{name}"
                    end
 
-          code << "api :#{api[:method]}, \"#{api[:path]}\""
-          code << ", \"#{desc}\"" if desc
+          code << "api :#{api[:method]}, '#{api[:path]}'"
+          code << ", '#{desc}'" if desc
           code << "\n"
         end
         return code
@@ -285,16 +307,16 @@ module Apipie
           desc[:type] = (desc[:type] && desc[:type].first) || Object
           code << "#{indent}param"
           if name =~ /\W/
-            code << " :\"#{name}\""
+            code << " :'#{name}'"
           else
             code << " :#{name}"
           end
           code << ", #{desc[:type].inspect}"
           if desc[:allow_nil]
-            code << ", :allow_nil => true"
+            code << ", allow_nil: true"
           end
           if desc[:required]
-            code << ", :required => true"
+            code << ", required: true"
           end
           if desc[:nested]
             code << " do\n"
@@ -310,7 +332,7 @@ module Apipie
       def generate_errors_code(errors)
         code = ""
         errors.sort_by {|e| e[:code] }.each do |error|
-          code << "error :code => #{error[:code]}\n"
+          code << "error code: #{error[:code]}\n"
         end
         code
       end