apipie-rails 0.0.13 → 0.0.14

data/apipie-rails.gemspec

@@ -16,13 +16,11 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.require_paths = ["lib"]
 
+  s.add_dependency "rails", ">= 3.0.10"
   s.add_development_dependency "rspec-rails"
-  s.add_development_dependency "rails", ">= 3.0.10"
   s.add_development_dependency "sqlite3"
   s.add_development_dependency "minitest"
-  s.add_development_dependency "redcarpet"
+  s.add_development_dependency "maruku"
   s.add_development_dependency "RedCloth"
   s.add_development_dependency "rake"
-  s.add_development_dependency "rest-client"
-  s.add_development_dependency "oauth"
 end

data/app/controllers/apipie/apipies_controller.rb

@@ -2,61 +2,39 @@ module Apipie
   class ApipiesController < ActionController::Base
     layout Apipie.configuration.layout
 
+    around_filter :set_script_name
+
     def index
+
+      params[:version] ||= Apipie.configuration.default_version
+
+      get_format
+
       respond_to do |format|
 
         if Apipie.configuration.use_cache?
-          path = Apipie.configuration.doc_base_url.dup
-          if [:resource, :method, :format].any? { |p| params[p].to_s =~ /\W/ }
-            head :bad_request and return
-          end
-
-          path << "/" << params[:resource] if params[:resource].present?
-          path << "/" << params[:method] if params[:method].present?
-          if params[:format].present?
-            path << ".#{params[:format]}"
-          else
-            path << ".html"
-          end
-          cache_file = File.join(Apipie.configuration.cache_dir, path)
-          if File.exists?(cache_file)
-            content_type = case params[:format]
-                           when "json" then "application/json"
-                           else "text/html"
-                           end
-            send_file cache_file, :type => content_type, :disposition => "inline"
-          else
-            Rails.logger.error("API doc cache not found for '#{path}'. Perhaps you have forgot to run `rake apipie:cache`")
-            head :not_found
-          end
-          return
+          render_from_cache and return
         end
 
         Apipie.reload_documentation if Apipie.configuration.reload_controllers?
-        @doc = Apipie.to_json(params[:resource], params[:method])
+        @doc = Apipie.to_json(params[:version], params[:resource], params[:method])
 
         format.json do
           render :json => @doc
         end
 
         format.html do
-
+          @versions = Apipie.available_versions
           @doc = @doc[:docs]
-          if params[:resource].present? && params[:method].present?
-            @resource = @doc[:resources].first
-            @method = @resource[:methods].first unless @resource == 'null'
-            if @resource == 'null' || @method == 'null'
-              render 'apipie_404', :status => 404
-            else
-              render 'method'
-            end
-          elsif params[:resource].present?
-            @resource = @doc[:resources].first
-            if @resource == 'null'
-              render 'apipie_404', :status => 404
-            else
-              render 'resource'
-            end
+          @resource = @doc[:resources].first if params[:resource].present?
+          @method = @resource[:methods].first if params[:method].present?
+
+          if @resource && @method
+            render 'method'
+          elsif @resource
+            render 'resource'
+          elsif params[:resource].present? || params[:method].present?
+            render 'apipie_404', :status => 404
           else
             render 'index'
           end
@@ -64,5 +42,59 @@ module Apipie
       end
     end
 
+    private
+
+    def get_format
+      params[:format] = :html unless params[:version].sub!('.html', '').nil?
+      params[:format] = :json unless params[:version].sub!('.json', '').nil?
+      request.format = params[:format] if params[:format]
+    end
+
+    def render_from_cache
+      path = Apipie.configuration.doc_base_url.dup
+      if [:resource, :method, :format].any? { |p| params[p].to_s =~ /\W/ }
+        head :bad_request and return
+      end
+      # version can contain dot, but only one in row
+      if params[:version].to_s.gsub(".", "") =~ /\W/ ||
+        params[:version].to_s =~ /\.\./
+        head :bad_request and return
+      end
+
+      path << "/" << params[:version] if params[:version].present?
+      path << "/" << params[:resource] if params[:resource].present?
+      path << "/" << params[:method] if params[:method].present?
+      if params[:format].present?
+        path << ".#{params[:format]}"
+      else
+        path << ".html"
+      end
+
+      # we sanitize the params before so in ideal case, this condition
+      # will be never satisfied. It's here for cases somebody adds new
+      # param into the path later and forgets about sanitation.
+      if path =~ /\.\./
+        head :bad_request and return
+      end
+
+      cache_file = File.join(Apipie.configuration.cache_dir, path)
+      if File.exists?(cache_file)
+        content_type = case params[:format]
+                       when "json" then "application/json"
+                       else "text/html"
+                       end
+        send_file cache_file, :type => content_type, :disposition => "inline"
+      else
+        Rails.logger.error("API doc cache not found for '#{path}'. Perhaps you have forgot to run `rake apipie:cache`")
+        head :not_found
+      end
+    end
+
+    def set_script_name
+      Apipie.request_script_name = request.env["SCRIPT_NAME"]
+      yield
+    ensure
+      Apipie.request_script_name = nil
+    end
   end
 end

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

@@ -1,14 +1,21 @@
 <ul class='breadcrumb'>
-  <li class='active'><a href='<%= @doc[:doc_url] %>.html'><%= @doc[:name] %></a></li>
+  <li class='active'><a href='<%= @doc[:doc_url] %>.html'><%= @doc[:name] %> <%= @doc[:resources].values.first[:version] %></a></li>
+  <% if @versions && @versions.size > 1 %>
+  <li class='pull-right'>
+    <%= @versions.collect { |v| link_to v, Apipie.full_url(v) }.join(' / ').html_safe %>
+  </li>
+  <% end %>
 </ul>
 
-<div><%= @doc[:info].html_safe %></div>
+<div><%= raw @doc[:info] %></div>
 
 <h1 class='page-header'>Resources</h1>
 
 <% @doc[:resources].sort_by(&:first).each do |key, api| %>
   <h2>
-    <a href='<%= api[:doc_url] %>.html'><%= api[:name] %></a><br>
+    <a href='<%= api[:doc_url] %>.html'>
+      <%= api[:name] %>
+    </a><br>
     <small><%= api[:short_description] %></small>
   </h2>
   <table class='table'>

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

@@ -1,10 +1,13 @@
 <ul class='breadcrumb'>
   <li>
-    <a href='<%= @doc[:doc_url] %>.html'><%= @doc[:name] %></a>
+    <a href='<%= @doc[:doc_url] %>.html'><%= @doc[:name] %> <%= @resource[:version] %></a>
     <span class='divider'>/</span>
   </li>
   <li>
-    <a href='<%= @resource[:doc_url] %>.html'><%= @resource[:name] %></a>
+    <a href='<%= @resource[:doc_url] %>.html'>
+      <%= @resource[:name] %>
+      <% if @resource[:version] %><% end %>
+    </a>
     <span class='divider'>/</span>
   </li>
   <li class='active'><%= @method[:name] %></li>

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

@@ -1,11 +1,18 @@
 <ul class='breadcrumb'>
-  <li><a href='<%= @doc[:doc_url] %>.html'><%= @doc[:name] %></a><span class='divider'>/</span></li>
-  <li class='active'><%= @resource[:name] %></li>
+  <li>
+    <a href='<%= @doc[:doc_url] %>.html'><%= @doc[:name] %> <%= @resource[:version] %></a>
+    <span class='divider'>/</span>
+  </li>
+  <li class='active'>
+    <%= @resource[:name] %>
+    <% if @resource[:version] %><% end %>
+  </li>
 </ul>
 
 <div class='page-header'>
   <h1>
-    <%= @resource[:name] %><br>
+    <%= @resource[:name] %>
+    <br>
     <small><%= raw @resource[:short_description] %></small>
   </h1>
 </div>

data/lib/apipie-rails.rb

@@ -1,6 +1,7 @@
 require "apipie/routing"
 require "apipie/markup"
 require "apipie/apipie_module"
+require "apipie/configuration"
 require "apipie/method_description"
 require "apipie/resource_description"
 require "apipie/param_description"

data/lib/apipie/apipie_module.rb

@@ -8,8 +8,9 @@ module Apipie
     @application ||= Apipie::Application.new
   end
 
-  def self.to_json(resource_name = nil, method_name = nil)
-    app.to_json(resource_name, method_name)
+  def self.to_json(version = nil, resource_name = nil, method_name = nil)
+    version ||= Apipie.configuration.default_version
+    app.to_json(version, resource_name, method_name)
   end
 
   # all calls delegated to Apipie::Application instance
@@ -25,89 +26,37 @@ module Apipie
     @configuration ||= Configuration.new
   end
 
-  class Configuration
-    attr_accessor :app_name, :app_info, :copyright, :markup, :disqus_shortname,
-      :validate, :api_base_url, :doc_base_url, :required_by_default, :layout
-
-    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
+  def self.debug(message)
+    puts message if Apipie.configuration.debug
+  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"
+  # get application description for given or default version
+  def self.app_info(version = nil)
+    if app_info_version_valid? version
+      Apipie.markup_to_html(self.configuration.app_info[version])
+    elsif app_info_version_valid? Apipie.configuration.default_version
+      Apipie.markup_to_html(self.configuration.app_info[Apipie.configuration.default_version])
+    else
+      "Another API description"
     end
+  end
 
-    def use_disqus?
-      !@disqus_shortname.blank?
+  def self.api_base_url(version = nil)
+    if api_base_url_version_valid? version
+      self.configuration.api_base_url[version]
+    elsif api_base_url_version_valid? Apipie.configuration.default_version
+      self.configuration.api_base_url[Apipie.configuration.default_version]
+    else
+      "/api"
     end
+  end
 
-    def app_info
-      Apipie.markup_to_html(@app_info)
-    end
+  def self.app_info_version_valid?(version)
+    version && self.configuration.app_info.has_key?(version)
+  end
 
-    def initialize
-      @markup = Apipie::Markup::RDoc.new
-      @app_name = "Another API"
-      @app_info = "Another API description"
-      @copyright = nil
-      @validate = true
-      @required_by_default = false
-      @api_base_url = ""
-      @doc_base_url = "/apipie"
-      @layout = "apipie/apipie"
-      @disqus_shortname = nil
-    end
+  def self.api_base_url_version_valid?(version)
+    version && self.configuration.api_base_url.has_key?(version)
   end
 
 end

data/lib/apipie/application.rb

@@ -12,147 +12,210 @@ module Apipie
       end
     end
 
-    attr_accessor :last_api_args, :last_errors, :last_params, :last_description, :last_examples, :last_see, :last_formats
-    attr_reader :method_descriptions, :resource_descriptions
+    attr_accessor :last_dsl_data
+
+    attr_reader :resource_descriptions
 
     def initialize
       super
-      @method_descriptions = Hash.new
-      @resource_descriptions = Hash.new
+      init_env
       clear_last
     end
 
+    def available_versions
+      @resource_descriptions.keys.sort
+    end
+
+    def set_resource_id(controller, resource_id)
+      @controller_to_resource_id[controller] = resource_id
+    end
+
     # create new method api description
-    def define_method_description(controller, method_name)
-      # create new or get existing api
-      resource_name = get_resource_name(controller)
-      key = [resource_name, method_name].join('#')
-      # add method description key to resource description
-      resource = define_resource_description(controller)
+    def define_method_description(controller, method_name, versions = [])
+      return if ignored?(controller, method_name)
+      ret_method_description = nil
+
+      versions = controller_versions(controller) if versions.empty?
+
+      versions.each do |version|
+        resource_name_with_version = "#{version}##{get_resource_name(controller)}"
+        resource_description = get_resource_description(resource_name_with_version)
 
-      method_description = Apipie::MethodDescription.new(method_name, resource, self)
+        if resource_description.nil?
+          resource_description = define_resource_description(controller, version)
+        end
+
+        method_description = Apipie::MethodDescription.new(method_name, resource_description, self)
 
-      @method_descriptions[key] ||= method_description
+        # we create separate method description for each version in
+        # case the method belongs to more versions. We return just one
+        # becuase the version doesn't matter for the purpose it's used
+        # (to wrap the original version with validators)
+        ret_method_description ||= method_description
+        resource_description.add_method_description(method_description)
+      end
 
-      @method_descriptions[key]
+      return ret_method_description
     end
 
     # create new resource api description
-    def define_resource_description(controller, &block)
+    def define_resource_description(controller, version, dsl_data = nil)
+      return if ignored?(controller)
+
       resource_name = get_resource_name(controller)
+      resource_description = @resource_descriptions[version][resource_name]
+      if resource_description
+        # we already defined the description somewhere (probably in
+        # some method. Updating just meta data from dsl
+        resource_description.update_from_dsl_data(dsl_data) if dsl_data
+      else
+        resource_description = Apipie::ResourceDescription.new(controller, resource_name, dsl_data, version)
+
+        Apipie.debug("@resource_descriptions[#{version}][#{resource_name}] = #{resource_description}")
+        @resource_descriptions[version][resource_name] ||= resource_description
+      end
+
+      return resource_description
+    end
 
-      # puts "defining api for #{resource_name}"
+    # recursively searches what versions has the controller specified in
+    # resource_description? It's used to derivate the default value of
+    # versions for methods.
+    def controller_versions(controller)
+      ret = @controller_versions[controller]
+      return ret unless ret.empty?
+      if controller == ActionController::Base || controller.nil?
+        return [Apipie.configuration.default_version]
+      else
+        return controller_versions(controller.superclass)
+      end
+    end
 
-      @resource_descriptions[resource_name] ||=
-        Apipie::ResourceDescription.new(controller, resource_name, &block)
+    def set_controller_versions(controller, versions)
+      @controller_versions[controller] = versions
     end
 
     def add_method_description_args(method, path, desc)
-      @last_api_args << MethodDescription::Api.new(method, path, desc)
+      @last_dsl_data[:api_args] << MethodDescription::Api.new(method, path, desc)
     end
 
     def add_example(example)
-      @last_examples << example.strip_heredoc
+      @last_dsl_data[:examples] << example.strip_heredoc
     end
 
     # check if there is some saved description
     def apipie_provided?
-      true unless last_api_args.blank?
+      true unless last_dsl_data[:api_args].blank?
     end
 
     # get api for given method
     #
     # There are two ways how this method can be used:
     # 1) Specify both parameters
-    #   resource_name: controller class or string with resource name (plural)
+    #   resource_name:
+    #       controller class - UsersController
+    #       string with resource name (plural) and version - "v1#users"
     #   method_name: name of the method (string or symbol)
+    #
     # 2) Specify only first parameter:
     #   resource_name: string containing both resource and method name joined
-    #   with # (eg. "users#create")
+    #   with '#' symbol.
+    #   - "users#create" get default version
+    #   - "v2#users#create" get specific version
     def get_method_description(resource_name, method_name = nil)
-      resource_name = get_resource_name(resource_name)
-      key = method_name.blank? ? resource_name : [resource_name, method_name].join('#')
-      @method_descriptions[key]
+      if resource_name.is_a?(String)
+        crumbs = resource_name.split('#')
+        if method_name.nil?
+          method_name = crumbs.pop
+        end
+        resource_name = crumbs.join("#")
+        resource_description = get_resource_description(resource_name)
+      elsif resource_name.respond_to? :apipie_resource_descriptions
+        resource_description = get_resource_description(resource_name)
+      else
+        raise ArgumentError.new("Resource #{resource_name} does not exists.")
+      end
+      unless resource_description.nil?
+        resource_description.method_description(method_name.to_sym)
+      end
     end
     alias :[] :get_method_description
 
-    # get api for given resource
-    def get_resource_description(resource_name)
-      resource_name = get_resource_name(resource_name)
-
-      @resource_descriptions[resource_name]
-    end
-
-    def remove_method_description(resource_name, method_name)
-      resource_name = get_resource_name(resource_name)
-
-      @method_descriptions.delete [resource_name, method_name].join('#')
-    end
-
-    def remove_resource_description(resource_name)
-      resource_name = get_resource_name(resource_name)
-
-      @resource_descriptions.delete resource_name
-    end
-
-    # Clear all apis in this application.
-    def clear
-      @resource_descriptions.clear
-      @method_descriptions.clear
-    end
-
-    # clear all saved data
-    def clear_last
-      @last_api_args = []
-      @last_errors = []
-      @last_params = []
-      @last_description = nil
-      @last_examples = []
-      @last_see = nil
-      @last_formats = []
-    end
+    # options:
+    # => "users"
+    # => "v2#users"
+    # =>  V2::UsersController
+    def get_resource_description(resource, version = nil)
+      if resource.is_a?(String)
+        crumbs = resource.split('#')
+        if crumbs.size == 2
+          version = crumbs.first
+        end
+        version ||= Apipie.configuration.default_version
+        if @resource_descriptions.has_key?(version)
+          return @resource_descriptions[version][crumbs.last]
+        end
+      else
+        resource_name = get_resource_name(resource)
+        if version
+          resource_name = "#{version}##{resource_name}"
+        end
 
-    # Return the current description, clearing it in the process.
-    def get_description
-      desc = @last_description
-      @last_description = nil
-      desc
+        if resource_name.nil?
+          return nil
+        end
+        resource_description = get_resource_description(resource_name)
+        if resource_description && resource_description.controller == resource
+          return resource_description
+        end
+      end
     end
 
-    def get_errors
-      errors = @last_errors.clone
-      @last_errors.clear
-      errors
+    # get all versions of resource description
+    def get_resource_descriptions(resource)
+      available_versions.map do |version|
+        get_resource_description(resource, version)
+      end.compact
     end
 
-    def get_api_args
-      api_args = @last_api_args.clone
-      @last_api_args.clear
-      api_args
+    # get all versions of method description
+    def get_method_descriptions(resource, method)
+      get_resource_descriptions(resource).map do |resource_description|
+        resource_description.method_description(method.to_sym)
+      end.compact
     end
 
-    def get_see
-      see = @last_see
-      @last_see = nil
-      see
+    def remove_method_description(resource, versions, method_name)
+      versions.each do |version|
+        resource = get_resource_name(resource)
+        if resource_description = get_resource_description("#{version}##{resource}")
+          resource_description.remove_method_description(method_name)
+        end
+      end
     end
 
-    def get_formats
-      formats = @last_formats
-      @last_formats = nil
-      formats
-    end
+    # initialize variables for gathering dsl data
+    def init_env
+      @resource_descriptions = HashWithIndifferentAccess.new { |h, version| h[version] = {} }
+      @controller_to_resource_id = {}
 
-    def get_params
-      params = @last_params.clone
-      @last_params.clear
-      params
+      # what versions does the controller belong in (specified by resource_description)?
+      @controller_versions = Hash.new { |h, controller| h[controller] = [] }
     end
-
-    def get_examples
-      examples = @last_examples.clone
-      @last_examples.clear
-      examples
+    # clear all saved data
+    def clear_last
+      @last_dsl_data = {
+        :api_args          => [],
+        :errors            => [],
+        :params            => [],
+        :resouce_id        => nil,
+        :short_description => nil,
+        :description       => nil,
+        :examples          => [],
+        :see               => nil,
+        :formats           => nil,
+        :api_versions      => []
+      }
     end
 
     def recorded_examples
@@ -170,26 +233,28 @@ module Apipie
       @recorded_examples = nil
     end
 
-    def to_json(resource_name, method_name)
+    def to_json(version, resource_name, method_name)
 
       _resources = if resource_name.blank?
         # take just resources which have some methods because
         # we dont want to show eg ApplicationController as resource
-        resource_descriptions.inject({}) do |result, (k,v)|
+        resource_descriptions[version].inject({}) do |result, (k,v)|
           result[k] = v.to_json unless v._methods.blank?
           result
         end
       else
-        [@resource_descriptions[resource_name].to_json(method_name)]
+        [@resource_descriptions[version][resource_name].to_json(method_name)]
       end
 
+      url_args = Apipie.configuration.version_in_url ? version : ''
+
       {
         :docs => {
           :name => Apipie.configuration.app_name,
-          :info => Apipie.configuration.app_info,
+          :info => Apipie.app_info(version),
           :copyright => Apipie.configuration.copyright,
-          :doc_url => Apipie.full_url(""),
-          :api_url => Apipie.configuration.api_base_url,
+          :doc_url => Apipie.full_url(url_args),
+          :api_url => Apipie.api_base_url(version),
           :resources => _resources
         }
       }
@@ -200,7 +265,10 @@ module Apipie
     end
 
     def reload_documentation
+      rails_mark_classes_for_reload
+      init_env
       reload_examples
+
       api_controllers_paths.each do |f|
         load_controller_from_file f
       end
@@ -218,8 +286,21 @@ module Apipie
     def get_resource_name(klass)
       if klass.class == String
         klass
+      elsif @controller_to_resource_id.has_key?(klass)
+        @controller_to_resource_id[klass]
       elsif klass.respond_to?(:controller_name)
+        return nil if klass == ActionController::Base
         klass.controller_name
+      else
+        raise "Apipie: Can not resolve resource #{klass} name."
+      end
+    end
+
+    def get_resource_version(resource_description)
+      if resource_description.respond_to? :_version
+        resource_description._version
+      else
+        Apipie.configuration.default_version
       end
     end
 
@@ -228,5 +309,21 @@ module Apipie
       controller_class_name.constantize
     end
 
+    def ignored?(controller, method = nil)
+      ignored = Apipie.configuration.ignored
+      return true if ignored.include?(controller.name)
+      return true if ignored.include?("#{controller.name}##{method}")
+    end
+
+    # Since Rails 3.2, the classes are reloaded only on file change.
+    # We need to reload all the controller classes to rebuild the
+    # docs, therefore we just force to reload all the code. This
+    # happens only when reload_controllers is set to true and only
+    # when showing the documentation.
+    def rails_mark_classes_for_reload
+      ActiveSupport::DescendantsTracker.clear
+      ActiveSupport::Dependencies.clear
+    end
+
   end
 end