apipie-rails 0.0.13 → 0.0.14

data/lib/apipie/client/generator.rb

@@ -17,12 +17,13 @@ module Apipie
       argument :name
       argument :subject
       argument :suffix
+      argument :version
 
       attr_reader :doc, :resource, :resource_key
 
       def initialize(*args)
         super
-        @doc = Apipie.to_json()[:docs]
+        @doc = Apipie.to_json(version)[:docs]
       end
 
       def self.source_root
@@ -33,10 +34,10 @@ module Apipie
         File.join(FileUtils.pwd, "#{name}#{suffix}")
       end
 
-      def self.start(client_name, subject = :all, suffix = '_client')
-        name   = client_name.parameterize.underscore
+      def self.start(client_name, subject = :all, suffix = '_client', version = nil)
+        name = client_name.parameterize.underscore
         suffix = suffix.parameterize.underscore
-        super([name, subject, suffix], :destination_root => destination_root(name, suffix))
+        super([name, subject, suffix, version], :destination_root => destination_root(name, suffix))
       end
 
       def all?

data/lib/apipie/configuration.rb

@@ -0,0 +1,112 @@
+module Apipie
+  class Configuration
+
+    attr_accessor :app_name, :app_info, :copyright, :markup, :disqus_shortname,
+      :validate, :api_base_url, :doc_base_url, :required_by_default, :layout,
+      :default_version, :debug, :version_in_url
+
+    alias_method :validate?, :validate
+    alias_method :required_by_default?, :required_by_default
+
+    # matcher to be used in Dir.glob to find controllers to be reloaded e.g.
+    #
+    #   "#{Rails.root}/app/controllers/api/*.rb"
+    attr_accessor :api_controllers_matcher
+
+    # set to true if you want to reload the controllers at each refresh of the
+    # documentation. It requires +:api_controllers_matcher+ to be set to work
+    # properly.
+    attr_writer :reload_controllers
+
+    def reload_controllers?
+      @reload_controllers = Rails.env.development? unless defined? @reload_controllers
+      return @reload_controllers && @api_controllers_matcher
+    end
+
+    # set to true if you want to use pregenerated documentation cache and avoid
+    # generating the documentation on runtime (usefull for production
+    # environment).
+    # You can generate the cache by running
+    #
+    #     rake apipie:cache
+    attr_accessor :use_cache
+    alias_method :use_cache?, :use_cache
+
+    attr_writer :cache_dir
+    def cache_dir
+      @cache_dir ||= File.join(Rails.root, "public", "apipie-cache")
+    end
+
+    # if there is not obvious reason why the DSL should be turned on (no
+    # validations, cache turned on etc.), it's disabled to avoid unneeded
+    # allocation. It you need the DSL for other reasons, you can force the
+    # activation.
+    attr_writer :force_dsl
+    def force_dsl?
+      @force_dsl
+    end
+
+    # array of controller names (strings) (might include actions as well)
+    # to be ignored # when extracting description form calls.
+    # e.g. %w[Api::CommentsController Api::PostsController#post]
+    attr_writer :ignored_by_recorder
+    def ignored_by_recorder
+      @ignored_by_recorder ||= []
+      @ignored_by_recorder.map(&:to_s)
+    end
+
+    # array of controller names (strings) (might include actions as well)
+    # to be ignored # when generationg the documentation
+    # e.g. %w[Api::CommentsController Api::PostsController#post]
+    attr_writer :ignored
+    def ignored
+      @ignored ||= []
+      @ignored.map(&:to_s)
+    end
+
+    # 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
+    # the line above the docs.
+    attr_writer :generated_doc_disclaimer
+    def generated_doc_disclaimer
+      @generated_doc_disclaimer ||= "# DOC GENERATED AUTOMATICALLY: REMOVE THIS LINE TO PREVENT REGENARATING NEXT TIME"
+    end
+
+    def use_disqus?
+      !@disqus_shortname.blank?
+    end
+
+    # set app description for default version
+    # to maintain backward compatibility
+    # new way: config.app_info[version] = description
+    def app_info=(description)
+      version = Apipie.configuration.default_version
+      @app_info[version] = description
+    end
+
+    # set base url for default version of API
+    # to set it for specific version use
+    # config.api_base_url[version] = url
+    def api_base_url=(url)
+      version = Apipie.configuration.default_version
+      @api_base_url[version] = url
+    end
+
+    def initialize
+      @markup = Apipie::Markup::RDoc.new
+      @app_name = "Another API"
+      @app_info = HashWithIndifferentAccess.new
+      @copyright = nil
+      @validate = true
+      @required_by_default = false
+      @api_base_url = HashWithIndifferentAccess.new
+      @doc_base_url = "/apipie"
+      @layout = "apipie/apipie"
+      @disqus_shortname = nil
+      @default_version = "1.0"
+      @debug = false
+      @version_in_url = true
+    end
+  end
+end

data/lib/apipie/dsl_definition.rb

@@ -5,6 +5,8 @@ module Apipie
   # DSL is a module that provides #api, #error, #param, #error.
   module DSL
 
+    attr_reader :apipie_resource_descriptions
+
     private
 
     # Describe whole resource
@@ -17,10 +19,74 @@ module Apipie
     # EOS
     def resource_description(options = {}, &block) #:doc:
       return unless Apipie.active_dsl?
-      Apipie.remove_resource_description(self)
-      Apipie.define_resource_description(self, &block) if block_given?
+      raise ArgumentError, "Block expected" unless block_given?
+
+      dsl_data = ResourceDescriptionDsl.eval_dsl(self, &block)
+      versions = dsl_data[:api_versions]
+      @apipie_resource_descriptions = versions.map do |version|
+        Apipie.define_resource_description(self, version, dsl_data)
+      end
+      Apipie.set_controller_versions(self, versions)
     end
 
+    class ResourceDescriptionDsl
+      include Apipie::DSL
+
+      NO_RESOURCE_KEYWORDS = %w[api see example]
+
+      NO_RESOURCE_KEYWORDS.each do |method|
+        define_method method do
+          raise "#{method} is not defined for resource description"
+        end
+      end
+
+      def initialize(controller)
+        @controller = controller
+      end
+
+      # by default, the resource id is derived from controller_name
+      # it can be overwritten with.
+      #
+      #    resource_id "my_own_resource_id"
+      def resource_id(resource_id)
+        Apipie.set_resource_id(@controller, resource_id)
+      end
+
+      def name(name)
+        Apipie.last_dsl_data[:resource_name] = name
+      end
+
+      def api_base_url(url)
+        Apipie.last_dsl_data[:api_base_url] = url
+      end
+
+      def short(short)
+        Apipie.last_dsl_data[:short_description] = short
+      end
+      alias :short_description :short
+
+      def path(path)
+        Apipie.last_dsl_data[:path] = path
+      end
+
+      def app_info(app_info)
+        Apipie.last_dsl_data[:app_info] = app_info
+      end
+
+      # evaluates resource description DSL and returns results
+      def self.eval_dsl(controller, &block)
+        self.new(controller).instance_eval(&block)
+        dsl_data = Apipie.last_dsl_data
+        if dsl_data[:api_versions].empty?
+          dsl_data[:api_versions] = Apipie.controller_versions(controller)
+        end
+        dsl_data
+      ensure
+        Apipie.clear_last
+      end
+    end
+
+
     # Declare an api.
     #
     # Example:
@@ -31,6 +97,11 @@ module Apipie
       Apipie.add_method_description_args(method, path, desc)
     end
 
+    def api_versions(*versions)
+      Apipie.last_dsl_data[:api_versions].concat(versions)
+    end
+    alias :api_version :api_versions
+
     # Describe the next method.
     #
     # Example:
@@ -41,12 +112,13 @@ module Apipie
     #
     def desc(description) #:doc:
       return unless Apipie.active_dsl?
-      if Apipie.last_description
+      if Apipie.last_dsl_data[:description]
         raise "Double method description."
       end
-      Apipie.last_description = description
+      Apipie.last_dsl_data[:description] = description
     end
     alias :description :desc
+    alias :full_description :desc
 
     # Reference other similar method
     #
@@ -55,8 +127,8 @@ module Apipie
     #   def update; end
     def see(method_key)
       return unless Apipie.active_dsl?
-      raise "'See' method called twice." if Apipie.last_see
-      Apipie.last_see = method_key
+      raise "'See' method called twice." if Apipie.last_dsl_data[:see]
+      Apipie.last_dsl_data[:see] = method_key
     end
 
     # Show some example of what does the described
@@ -71,7 +143,7 @@ module Apipie
     #   formats ['json', 'jsonp', 'xml']
     def formats(formats) #:doc:
       return unless Apipie.active_dsl?
-      Apipie.last_formats = formats
+      Apipie.last_dsl_data[:formats] = formats
     end
 
     # Describe possible errors
@@ -86,7 +158,7 @@ module Apipie
     #
     def error(*args) #:doc:
       return unless Apipie.active_dsl?
-      Apipie.last_errors << Apipie::ErrorDescription.new(args)
+      Apipie.last_dsl_data[:errors] << Apipie::ErrorDescription.new(args)
     end
 
     # Describe method's parameter
@@ -99,22 +171,28 @@ module Apipie
     #
     def param(param_name, validator, desc_or_options = nil, options = {}, &block) #:doc:
       return unless Apipie.active_dsl?
-      Apipie.last_params << Apipie::ParamDescription.new(param_name, validator, desc_or_options, options, &block)
+      Apipie.last_dsl_data[:params] << Apipie::ParamDescription.new(param_name, validator, desc_or_options, options, &block)
     end
 
     # create method api and redefine newly added method
     def method_added(method_name) #:doc:
       super
 
-      return unless Apipie.active_dsl?
-      return unless Apipie.apipie_provided?
+      if ! Apipie.active_dsl? || ! Apipie.apipie_provided?
+        Apipie.clear_last
+        return
+      end
 
-      # remove method description if exists and create new one
-      Apipie.remove_method_description(self, method_name)
-      description = Apipie.define_method_description(self, method_name)
+      begin
+        # remove method description if exists and create new one
+        Apipie.remove_method_description(self, Apipie.last_dsl_data[:api_versions], method_name)
+        description = Apipie.define_method_description(self, method_name, Apipie.last_dsl_data[:api_versions])
+      ensure
+        Apipie.clear_last
+      end
 
       # redefine method only if validation is turned on
-      if Apipie.configuration.validate == true
+      if description && Apipie.configuration.validate == true
 
         old_method = instance_method(method_name)
 
@@ -141,7 +219,6 @@ module Apipie
         end
 
       end
-
     end # def method_added
   end # module DSL
 end # module Apipie

data/lib/apipie/extractor.rb

@@ -53,10 +53,11 @@ module Apipie
         Writer.new(@collector).write_examples if @collector
       end
 
+      # TODO: this is a loooooooooong method :)
       def apis_from_routes
         return @apis_from_routes if @apis_from_routes
 
-        api_prefix = Apipie.configuration.api_base_url.sub(/\/$/,"")
+        api_prefix = Apipie.api_base_url.sub(/\/$/,"")
         all_routes = Rails.application.routes.routes.map do |r|
           {
             :verb => case r.verb
@@ -74,7 +75,7 @@ module Apipie
 
         end
         api_routes = all_routes.find_all do |r|
-          r[:path].starts_with?(Apipie.configuration.api_base_url)
+          r[:path].starts_with?(Apipie.api_base_url)
         end
 
         @apis_from_routes = Hash.new { |h, k| h[k] = [] }
@@ -97,9 +98,12 @@ module Apipie
         end
         @apis_from_routes
 
-        apis_from_docs = Apipie.method_descriptions.reduce({}) do |h, (method, desc)|
+        method_descriptions = Apipie.resource_descriptions.map(&:method_descriptions).flatten
+        apis_from_docs = method_descriptions.reduce({}) do |h, (method, desc)|
           apis = desc.apis.map do |api|
-            {:method => api.http_method, :path => api.api_url, :desc => api.short_description}
+            { :method => api.http_method,
+              :path => api.api_url,
+              :desc => api.short_description }
           end
           h.update(method => apis)
         end
@@ -109,7 +113,10 @@ module Apipie
           old_apis = apis_from_docs[method_key] || []
           new_apis.each do |new_api|
             new_api[:path].sub!(/\(\.:format\)$/,"")
-            if old_api = old_apis.find { |api| api[:path] == "#{api_prefix}#{new_api[:path]}" }
+            old_api = old_apis.find do |api|
+              api[:path] == "#{api_prefix}#{new_api[:path]}"
+            end
+            if old_api
               new_api[:desc] = old_api[:desc]
             end
           end

data/lib/apipie/extractor/collector.rb

@@ -92,7 +92,7 @@ module Apipie
       end
 
       def add_routes_info(desc)
-        api_prefix = Apipie.configuration.api_base_url.sub(/\/$/,"")
+        api_prefix = Apipie.api_base_url.sub(/\/$/,"")
         desc[:api] = Apipie::Extractor.apis_from_routes[[desc[:controller].name, desc[:action]]]
         if desc[:api]
           desc[:params].each do |name, param|

data/lib/apipie/extractor/recorder.rb

@@ -109,8 +109,9 @@ module Apipie
         end
 
         def process_with_api_recording(*args) # action, parameters = nil, session = nil, flash = nil, http_method = 'GET')
-          process_without_api_recording(*args)
+          ret = process_without_api_recording(*args)
           Apipie::Extractor.call_recorder.analyze_functional_test(self)
+          ret
         ensure
           Apipie::Extractor.call_finished
         end

data/lib/apipie/extractor/writer.rb

@@ -1,3 +1,5 @@
+require 'set'
+
 module Apipie
   module Extractor
     class Writer
@@ -47,7 +49,7 @@ module Apipie
       def ordered_call(call)
         call = call.stringify_keys
         ordered_call = OrderedHash.new
-        %w[verb path query request_data response_data code show_in_doc recorded].each do |k|
+        %w[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
@@ -76,10 +78,15 @@ module Apipie
 
       def load_new_examples
         @collector.records.reduce({}) do |h, (method, calls)|
-          show_in_doc = nil
+          showed_in_versions = Set.new
+          # we have already shown some example
           recorded_examples = calls.map do |call|
-            if show_in_doc.nil?
-              show_in_doc = 1 if showable_in_doc?(call.with_indifferent_access)
+            method_descriptions = Apipie.get_method_descriptions(call[:controller], call[:action])
+            call[:versions] = method_descriptions.map(&:version)
+
+            if call[:versions].any? { |v| ! showed_in_versions.include?(v) }
+              call[:versions].each { |v| showed_in_versions << v }
+              show_in_doc = 1
             else
               show_in_doc = 0
             end

data/lib/apipie/helpers.rb

@@ -1,17 +1,28 @@
 module Apipie
   module Helpers
     def markup_to_html(text)
-      Apipie.configuration.markup.to_html(text.strip_heredoc)
+      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 = ""
-        if rails_prefix = ENV["RAILS_RELATIVE_URL_ROOT"]
-          @url_prefix << rails_prefix
-        end
+        @url_prefix << request_script_name
         @url_prefix << Apipie.configuration.doc_base_url
       end
       path = path.sub(/^\//,"")