apipierails3 0.0.1

data/lib/apipie/helpers.rb

@@ -0,0 +1,73 @@
+module Apipie
+  module Helpers
+    def markup_to_html(text)
+      return "" if text.nil?
+      if Apipie.configuration.markup.respond_to? :to_html
+        Apipie.configuration.markup.to_html(text.strip_heredoc)
+      else
+        text.strip_heredoc
+      end
+    end
+
+    attr_accessor :url_prefix
+
+    def request_script_name
+      Thread.current[:apipie_req_script_name] || ""
+    end
+
+    def request_script_name=(script_name)
+      Thread.current[:apipie_req_script_name] = script_name
+    end
+
+    def full_url(path)
+      unless @url_prefix
+        @url_prefix = ""
+        @url_prefix << request_script_name
+        @url_prefix << Apipie.configuration.doc_base_url
+      end
+      path = path.sub(/^\//,"")
+      ret = "#{@url_prefix}/#{path}"
+      ret.insert(0,"/") unless ret =~ /\A[.\/]/
+      ret.sub!(/\/*\Z/,"")
+      ret
+    end
+
+    def include_javascripts
+      %w[ bundled/jquery.js
+          bundled/bootstrap-collapse.js
+          bundled/prettify.js
+          apipie.js ].map do |file|
+        "<script type='text/javascript' src='#{Apipie.full_url("javascripts/#{file}")}'></script>"
+      end.join("\n").html_safe
+    end
+
+    def include_stylesheets
+      %w[ bundled/bootstrap.min.css
+          bundled/prettify.css
+          bundled/bootstrap-responsive.min.css ].map do |file|
+        "<link type='text/css' rel='stylesheet' href='#{Apipie.full_url("stylesheets/#{file}")}'/>"
+      end.join("\n").html_safe
+    end
+
+    def label_class_for_error(err)
+      case err[:code]
+        when 200
+          'label label-info'
+        when 201
+          'label label-success'
+        when 204
+          'label label-info2'
+        when 401
+          'label label-warning'
+        when 403
+          'label label-warning2'
+        when 422
+          'label label-important'
+        when 404
+          'label label-inverse'
+        else
+          'label'
+      end
+    end
+  end
+end

data/lib/apipie/markup.rb

@@ -0,0 +1,48 @@
+module Apipie
+
+  module Markup
+
+    class RDoc
+
+      def initialize
+        require 'rdoc'
+        require 'rdoc/markup/to_html'
+        if Gem::Version.new(::RDoc::VERSION) < Gem::Version.new('4.0.0')
+          @rdoc ||= ::RDoc::Markup::ToHtml.new()
+        else
+          @rdoc ||= ::RDoc::Markup::ToHtml.new(::RDoc::Options.new)
+        end
+      end
+
+      def to_html(text)
+        @rdoc.convert(text)
+      end
+
+    end
+
+    class Markdown
+
+      def initialize
+        require 'maruku'
+      end
+
+      def to_html(text)
+        Maruku.new(text).to_html
+      end
+
+    end
+
+    class Textile
+
+      def initialize
+        require 'RedCloth'
+      end
+
+      def to_html(text)
+        RedCloth.new(text).to_html
+      end
+
+    end
+
+  end
+end

data/lib/apipie/method_description.rb

@@ -0,0 +1,273 @@
+require 'set'
+module Apipie
+
+  class MethodDescription
+
+    class Api
+
+      attr_accessor :short_description, :path, :http_method, :from_routes, :options, :returns
+
+      def initialize(method, path, desc, options)
+        @http_method = method.to_s
+        @path = path
+        @short_description = desc
+        @from_routes = options[:from_routes]
+        @options = options
+      end
+
+    end
+
+    attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats, :metadata, :headers, :show
+
+    def initialize(method, resource, dsl_data)
+      @method = method.to_s
+      @resource = resource
+      @from_concern = dsl_data[:from_concern]
+      @apis = api_data(dsl_data).map do |mthd, path, desc, opts|
+        MethodDescription::Api.new(mthd, concern_subst(path), concern_subst(desc), opts)
+      end
+
+      desc = dsl_data[:description] || ''
+      @full_description = Apipie.markup_to_html(desc)
+
+      @errors = dsl_data[:errors].map do |args|
+        Apipie::ErrorDescription.from_dsl_data(args)
+      end
+
+      @tag_list = dsl_data[:tag_list]
+
+      @returns = dsl_data[:returns].map do |code,args|
+        Apipie::ResponseDescription.from_dsl_data(self, code, args)
+      end
+
+      @see = dsl_data[:see].map do |args|
+        Apipie::SeeDescription.new(args)
+      end
+
+      @formats = dsl_data[:formats]
+      @examples = dsl_data[:examples]
+      @examples += load_recorded_examples
+
+      @metadata = dsl_data[:meta]
+
+      @params_ordered = dsl_data[:params].map do |args|
+        Apipie::ParamDescription.from_dsl_data(self, args)
+      end.reject{|p| p.response_only? }
+
+      @params_ordered = ParamDescription.unify(@params_ordered)
+      @headers = dsl_data[:headers]
+
+      @show = if dsl_data.has_key? :show
+        dsl_data[:show]
+      else
+        true
+      end
+    end
+
+    def id
+      "#{resource._id}##{method}"
+    end
+
+    def params
+      params_ordered.reduce(ActiveSupport::OrderedHash.new) { |h,p| h[p.name] = p; h }
+    end
+
+    def params_ordered_self
+      @params_ordered
+    end
+
+    def params_ordered
+      all_params = []
+      parent = Apipie.get_resource_description(@resource.controller.superclass)
+
+      # get params from parent resource description
+      [parent, @resource].compact.each do |resource|
+        resource_params = resource._params_args.map do |args|
+          Apipie::ParamDescription.from_dsl_data(self, args)
+        end
+        merge_params(all_params, resource_params)
+      end
+
+      merge_params(all_params, @params_ordered)
+      all_params.find_all(&:validator)
+    end
+
+    def returns_self
+      @returns
+    end
+
+    def tag_list
+      all_tag_list = []
+      parent = Apipie.get_resource_description(@resource.controller.superclass)
+
+      # get tags from parent resource description
+      parent_tags = [parent, @resource].compact.flat_map { |resource| resource._tag_list_arg }
+      Apipie::TagListDescription.new((parent_tags + @tag_list).uniq.compact)
+    end
+
+    def returns
+      all_returns = []
+      parent = Apipie.get_resource_description(@resource.controller.superclass)
+
+      # get response descriptions from parent resource description
+      [parent, @resource].compact.each do |resource|
+        resource_returns = resource._returns_args.map do |code, args|
+          Apipie::ResponseDescription.from_dsl_data(self, code, args)
+        end
+        merge_returns(all_returns, resource_returns)
+      end
+
+      merge_returns(all_returns, @returns)
+    end
+
+    def errors
+      return @merged_errors if @merged_errors
+      @merged_errors = []
+      if @resource
+        resource_errors = @resource._errors_args.map do |args|
+          Apipie::ErrorDescription.from_dsl_data(args)
+        end
+
+        # exclude overwritten parent errors
+        @merged_errors = resource_errors.find_all do |err|
+          !@errors.any? { |e| e.code == err.code }
+        end
+      end
+      @merged_errors.concat(@errors)
+      return @merged_errors
+    end
+
+    def version
+      resource._version
+    end
+
+    def doc_url
+      crumbs = []
+      crumbs << @resource._version if Apipie.configuration.version_in_url
+      crumbs << @resource._id
+      crumbs << @method
+      Apipie.full_url crumbs.join('/')
+    end
+
+    def create_api_url(api)
+      path = api.path
+      unless api.from_routes
+        path = "#{@resource._api_base_url}#{path}"
+      end
+      path = path[0..-2] if path[-1..-1] == '/'
+      return path
+    end
+
+    def method_apis_to_json(lang = nil)
+      @apis.each.collect do |api|
+        {
+          :api_url => create_api_url(api),
+          :http_method => api.http_method.to_s,
+          :short_description => Apipie.app.translate(api.short_description, lang),
+          :deprecated => resource._deprecated || api.options[:deprecated]
+        }
+      end
+    end
+
+    def see
+      @see
+    end
+
+    def formats
+      @formats || @resource._formats
+    end
+
+    def to_json(lang=nil)
+      {
+        :doc_url => doc_url,
+        :name => @method,
+        :apis => method_apis_to_json(lang),
+        :formats => formats,
+        :full_description => Apipie.app.translate(@full_description, lang),
+        :errors => errors.map(&:to_json),
+        :params => params_ordered.map{ |param| param.to_json(lang) }.flatten,
+        :returns => @returns.map{ |return_item| return_item.to_json(lang) }.flatten,
+        :examples => @examples,
+        :metadata => @metadata,
+        :see => see.map(&:to_json),
+        :headers => headers,
+        :show => @show
+      }
+    end
+
+    # was the description defines in a module instead of directly in controller?
+    def from_concern?
+      @from_concern
+    end
+
+    private
+
+    def api_data(dsl_data)
+      ret = dsl_data[:api_args].dup
+      if dsl_data[:api_from_routes]
+        desc = dsl_data[:api_from_routes][:desc]
+        options = dsl_data[:api_from_routes][:options]
+
+        api_from_routes = Apipie.routes_for_action(resource.controller, method, {: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
+        ret.concat(api_from_routes)
+      end
+      ret
+    end
+
+    def merge_params(params, new_params)
+      new_param_names = Set.new(new_params.map(&:name))
+      params.delete_if { |p| new_param_names.include?(p.name) }
+      params.concat(new_params)
+    end
+
+    def merge_returns(returns, new_returns)
+      new_return_codes = Set.new(new_returns.map(&:code))
+      returns.delete_if { |p| new_return_codes.include?(p.code) }
+      returns.concat(new_returns)
+    end
+
+    def load_recorded_examples
+      (Apipie.recorded_examples[id] || []).
+        find_all { |ex| ex["show_in_doc"].to_i > 0 }.
+        find_all { |ex| ex["versions"].nil? || ex["versions"].include?(self.version) }.
+        sort_by { |ex| ex["show_in_doc"] }.
+        map { |ex| format_example(ex.symbolize_keys) }
+    end
+
+    def format_example_data(data)
+      case data
+      when Array, Hash
+        JSON.pretty_generate(data).gsub(/: \[\s*\]/,": []").gsub(/\{\s*\}/,"{}")
+      else
+        data
+      end
+    end
+
+    def format_example(ex)
+      example = ""
+      example << "// #{ex[:title]}\n" if ex[:title].present?
+      example << "#{ex[:verb]} #{ex[:path]}"
+      example << "?#{ex[:query]}" unless ex[:query].blank?
+      example << "\n" << format_example_data(ex[:request_data]).to_s if ex[:request_data]
+      example << "\n" << ex[:code].to_s
+      example << "\n" << format_example_data(ex[:response_data]).to_s if ex[:response_data]
+      example
+    end
+
+    def concern_subst(string)
+      return if string.nil?
+      if from_concern?
+        resource.controller._apipie_perform_concern_subst(string)
+      else
+        string
+      end
+    end
+
+  end
+
+end

data/lib/apipie/middleware/checksum_in_headers.rb

@@ -0,0 +1,35 @@
+# Middleware for rails app that adds checksum of JSON in the response headers
+# which can help client to realize when JSON has changed
+#
+# Add the following to your application.rb
+#   require 'apipie/middleware/checksum_in_headers'
+#   # Add JSON checksum in headers for smarter caching
+#   config.middleware.use "Apipie::Middleware::ChecksumInHeaders"
+#
+# And in your apipie initializer allow checksum calculation
+#   Apipie.configuration.update_checksum = true
+# and reload documentation
+#   Apipie.reload_documentation
+#
+# By default the header is added to requests on /api and /apipie only
+# It can be changed with
+#   Apipie.configuration.checksum_path = ['/prefix/api']
+# If set to nil the header is added always
+
+module Apipie
+  module Middleware
+    class ChecksumInHeaders
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        status, headers, body = @app.call(env)
+        if !Apipie.configuration.checksum_path || env['PATH_INFO'].start_with?(*Apipie.configuration.checksum_path)
+          headers.merge!( 'Apipie-Checksum' => Apipie.checksum )
+        end
+        return [status, headers, body]
+      end
+    end
+  end
+end

data/lib/apipie/param_description.rb

@@ -0,0 +1,280 @@
+module Apipie
+
+  # method parameter description
+  #
+  # name - method name (show)
+  # desc - description
+  # required - boolean if required
+  # validator - Validator::BaseValidator subclass
+  class ParamDescription
+
+    attr_reader :method_description, :name, :desc, :allow_nil, :allow_blank, :validator, :options, :metadata, :show, :as, :validations, :response_only, :request_only
+    attr_reader :additional_properties, :is_array
+    attr_accessor :parent, :required
+
+    alias_method :response_only?, :response_only
+    alias_method :request_only?, :request_only
+    alias_method :is_array?, :is_array
+
+    def self.from_dsl_data(method_description, args)
+      param_name, validator, desc_or_options, options, block = args
+      Apipie::ParamDescription.new(method_description,
+                                   param_name,
+                                   validator,
+                                   desc_or_options,
+                                   options,
+                                   &block)
+    end
+
+    def to_s
+      "ParamDescription: #{method_description.id}##{name}"
+    end
+
+    def ==(other)
+      return false unless self.class == other.class
+      if method_description == other.method_description && @options == other.options
+        true
+      else
+        false
+      end
+    end
+
+    def initialize(method_description, name, validator, desc_or_options = nil, options = {}, &block)
+
+      if desc_or_options.is_a?(Hash)
+        options = options.merge(desc_or_options)
+      elsif desc_or_options.is_a?(String)
+        options[:desc] = desc_or_options
+      elsif !desc_or_options.nil?
+        raise ArgumentError.new("param description: expected description or options as 3rd parameter")
+      end
+
+      options.symbolize_keys!
+
+      # we save options to know what was passed in DSL
+      @options = options
+      if @options[:param_group]
+        @from_concern = @options[:param_group][:from_concern]
+      end
+
+      @method_description = method_description
+      @name = concern_subst(name)
+      @as = options[:as] || @name
+      @desc = preformat_text(@options[:desc])
+
+      @parent = @options[:parent]
+      @metadata = @options[:meta]
+
+      @required = is_required?
+
+      @response_only = (@options[:only_in] == :response)
+      @request_only = (@options[:only_in] == :request)
+      raise ArgumentError.new("'#{@options[:only_in]}' is not a valid value for :only_in") if (!@response_only && !@request_only) && @options[:only_in].present?
+
+      @show = if @options.has_key? :show
+        @options[:show]
+      else
+        true
+      end
+
+      @allow_nil = @options[:allow_nil] || false
+      @allow_blank = @options[:allow_blank] || false
+
+      action_awareness
+
+      if validator
+        if (validator != Hash) && (validator.is_a? Hash) && (validator[:array_of])
+          @is_array = true
+          rest_of_options = validator
+          validator = validator[:array_of]
+          options.merge!(rest_of_options.select{|k,v| k != :array_of })
+          raise "an ':array_of =>' validator is allowed exclusively on response-only fields" unless @response_only
+        end
+        @validator = Validator::BaseValidator.find(self, validator, @options, block)
+        raise "Validator for #{validator} not found." unless @validator
+      end
+
+      @validations = Array(options[:validations]).map {|v| concern_subst(Apipie.markup_to_html(v)) }
+
+      @additional_properties = @options[:additional_properties]
+    end
+
+    def from_concern?
+      method_description.from_concern? || @from_concern
+    end
+
+    def normalized_value(value)
+      if value.is_a?(ActionController::Parameters) && !value.is_a?(Hash)
+        value.to_unsafe_hash
+      elsif value.is_a? Array
+        value.map { |v| normalized_value (v) }
+      else
+        value
+      end
+    end
+
+    def validate(value)
+      return true if @allow_nil && value.nil?
+      return true if @allow_blank && value.blank?
+      value = normalized_value(value)
+      if (!@allow_nil && value.nil?) || !@validator.valid?(value)
+        error = @validator.error
+        error = ParamError.new(error) unless error.is_a? StandardError
+        raise error
+      end
+    end
+
+    def process_value(value)
+      value = normalized_value(value)
+      if @validator.respond_to?(:process_value)
+        @validator.process_value(value)
+      else
+        value
+      end
+    end
+
+    def full_name
+      name_parts = parents_and_self.map{|p| p.name if p.show}.compact
+      return name.to_s if name_parts.blank?
+      return ([name_parts.first] + name_parts[1..-1].map { |n| "[#{n}]" }).join("")
+    end
+
+    # returns an array of all the parents: starting with the root parent
+    # ending with itself
+    def parents_and_self
+      ret = []
+      if self.parent
+        ret.concat(self.parent.parents_and_self)
+      end
+      ret << self
+      ret
+    end
+
+    def to_json(lang = nil)
+      hash = { :name => name.to_s,
+               :full_name => full_name,
+               :description => preformat_text(Apipie.app.translate(@options[:desc], lang)),
+               :required => required,
+               :allow_nil => allow_nil,
+               :allow_blank => allow_blank,
+               :validator => validator.to_s,
+               :expected_type => validator.expected_type,
+               :metadata => metadata,
+               :show => show,
+               :validations => validations }
+      if sub_params = validator.params_ordered
+        hash[:params] = sub_params.map { |p| p.to_json(lang)}
+      end
+      hash
+    end
+
+    def merge_with(other_param_desc)
+      if self.validator && other_param_desc.validator
+        self.validator.merge_with(other_param_desc.validator)
+      else
+        self.validator ||= other_param_desc.validator
+      end
+      self
+    end
+
+    # merge param descriptions. Allows defining hash params on more places
+    # (e.g. in param_groups). For example:
+    #
+    #     def_param_group :user do
+    #       param :user, Hash do
+    #         param :name, String
+    #       end
+    #     end
+    #
+    #     param_group :user
+    #     param :user, Hash do
+    #       param :password, String
+    #     end
+    def self.unify(params)
+      ordering = params.map(&:name)
+      params.group_by(&:name).map do |name, param_descs|
+        param_descs.reduce(&:merge_with)
+      end.sort_by { |param| ordering.index(param.name) }
+    end
+
+    def self.merge(target_params, source_params)
+      params_to_merge, params_to_add = source_params.partition do |source_param|
+        target_params.any? { |target_param| source_param.name == target_param.name }
+      end
+      unify(target_params + params_to_merge)
+      target_params.concat(params_to_add)
+    end
+
+    # action awareness is being inherited from ancestors (in terms of
+    # nested params)
+    def action_aware?
+      if @options.has_key?(:action_aware)
+        return @options[:action_aware]
+      elsif @parent
+        @parent.action_aware?
+      else
+        false
+      end
+    end
+
+    def as_action
+      if @options[:param_group] && @options[:param_group][:options] &&
+          @options[:param_group][:options][:as]
+        @options[:param_group][:options][:as].to_s
+      elsif @parent
+        @parent.as_action
+      else
+        @method_description.method
+      end
+    end
+
+    # makes modification that are based on the action that the param
+    # is defined for. Typical for required and allow_nil variations in
+    # crate/update actions.
+    def action_awareness
+      if action_aware?
+        if !@options.has_key?(:allow_nil)
+          if @required
+            @allow_nil = false
+          else
+            @allow_nil = true
+          end
+        end
+        if as_action != "create"
+          @required = false
+        end
+      end
+    end
+
+    def concern_subst(string)
+      return string if string.nil? or !from_concern?
+
+      original = string
+      string = ":#{original}" if original.is_a? Symbol
+
+      replaced = method_description.resource.controller._apipie_perform_concern_subst(string)
+
+      return original if replaced == string
+      return replaced.to_sym if original.is_a? Symbol
+      return replaced
+    end
+
+    def preformat_text(text)
+      concern_subst(Apipie.markup_to_html(text || ''))
+    end
+
+    def is_required?
+      if @options.has_key?(:required)
+        if (@options[:required] == true) || (@options[:required] == false)
+          @options[:required]
+        else
+          Array(@options[:required]).include?(@method_description.method.to_sym)
+        end
+      else
+        Apipie.configuration.required_by_default?
+      end
+    end
+
+  end
+
+end