restapi 0.0.4 → 0.0.5

data/Gemfile

@@ -9,5 +9,4 @@ group :development, :test do
   gem "redcarpet"
   gem "RedCloth"
   gem "rake"
-  gem "weary", ">= 1.0.1"
 end

data/Gemfile.lock

@@ -29,7 +29,6 @@ GEM
     activesupport (3.2.3)
       i18n (~> 0.6)
       multi_json (~> 1.0)
-    addressable (2.2.8)
     arel (3.0.2)
     builder (3.0.0)
     diff-lcs (1.1.3)
@@ -45,7 +44,6 @@ GEM
     mime-types (1.18)
     multi_json (1.2.0)
     polyglot (0.3.3)
-    promise (0.3.0)
     rack (1.4.1)
     rack-cache (1.2)
       rack (>= 0.4)
@@ -85,7 +83,6 @@ GEM
       activesupport (>= 3.0)
       railties (>= 3.0)
       rspec (~> 2.10.0)
-    simple_oauth (0.1.8)
     sprockets (2.1.3)
       hike (~> 1.2)
       rack (~> 1.0)
@@ -97,12 +94,6 @@ GEM
       polyglot
       polyglot (>= 0.3.1)
     tzinfo (0.3.33)
-    weary (1.0.1)
-      addressable (~> 2.2.7)
-      multi_json (~> 1.2.0)
-      promise (~> 0.3.0)
-      rack (~> 1.4.0)
-      simple_oauth (~> 0.1.5)
 
 PLATFORMS
   ruby
@@ -114,4 +105,3 @@ DEPENDENCIES
   redcarpet
   rspec-rails
   sqlite3
-  weary (>= 1.0.1)

data/README.rdoc

@@ -88,7 +88,7 @@ Example:
       config.markup = Restapi::Markup::Markdown.new
       config.reload_controllers = true
       config.api_controllers_matcher = File.join(Rails.root, "app", "controllers", "**","*.rb")
-      config.app_info < <-DOC
+      config.app_info = <<-DOC
         This is where you can inform user about your application and API
         in general.
       DOC
@@ -135,7 +135,7 @@ Example:
           param :password, String, :required => true,
                 :desc => "Password for login"
         end
-        description < <-DOC
+        description <<-DOC
           Full description of this resource.
         DOC
       end
@@ -160,6 +160,8 @@ Then describe methods available to your API.
               choosen markup language processor.
 [example] Provide example of server response, whole communication or response type.
           It will be formatted as code.
+[see] Provide reference to another method, this has to be string with
+      controller_name#method_name. 
 
 Example:
 
@@ -175,6 +177,7 @@ Example:
    }, :desc => "proc validator"
    description "method description"
    example " 'user': {...} "
+   see "users#showme"
    def show
      #...
    end
@@ -356,21 +359,24 @@ or delete it if you want to use 'normal' dynamic version again.
 
 == CLI client
 
-If you provide enough info about your API, you can generate simple CLI client. It is rather skeleton but sufficient for simple use. There is rake task for it: <tt>rake restapi:client</tt>. You can run it with two arguments <tt>rake restapi:client[http://api.example.com,.json]</tt>. The first argument is API base URL (default is http://localhost:3000). Value of second argument is appended to every URL (empty by default) which can be used to specify format. This two values can be also set afterwards from your environment as API_URL and URL_APPEND.
+If you provide enough info about your API, you can generate simple CLI client. It is rather skeleton but sufficient for simple use. There is rake task for it: <tt>rake restapi:client</tt>.
 
-This task create *clients* directory with two files. <tt>Base.rb</tt> contains {Weary}[https://github.com/mwunsch/weary] clients which you can use in your own program, for howto look at {Weary}[https://github.com/mwunsch/weary] documentation. <tt>cli.thor</tt> contains {Thor}[https://github.com/wycats/thor] classes for easy interaction from cli.
+This task create *clients* directory with client files.
+It uses {REST Client}[https://github.com/archiloque/rest-client] for HTTP communication and {Thor}[https://github.com/wycats/thor] for easy interaction from cli.
 
 Example usage:
 
-    thor list             # list of all available resources and methods
-    thor help users:show  # method and its parameters description
-    thor users:show --id=5 --session=abc # get /users/5?session=abc and print response body
-    thor users:create --user=username:foo password:bar
+    ./bin/client             # list of all available resources
+    ./bin/client user  # list of methods with description
+    ./bin/client user help show # show method description and parameters
+    ./bin/client help user:show
+    ./bin/client user show --id=5 --screen-name=pajk  # get /users/5?screen_name=pajk and print response body
+    ./bin/client user create --user=username:foo password:bar
 
-== TODO
+== {Extractor}[https://github.com/Pajk/rails-restapi/wiki/Extractor]
+
+== Future features
 
 * Dynamic CLI client (read info from documentation API)
 * Add documentation json API description to readme
-[Ideas] * PDF documentation generator
-        * Possibility to create requests from web documentation and check responses
-
+* Possibility to create requests from web documentation and check responses

data/app/controllers/restapi/restapis_controller.rb

@@ -4,7 +4,34 @@ module Restapi
     
     def index
       respond_to do |format|
-       
+
+        if Restapi.configuration.use_cache?
+          path = Restapi.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(Restapi.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 restapi:cache`")
+            head :not_found
+          end
+          return
+        end
+
         Restapi.reload_documentation if Restapi.configuration.reload_controllers?
         @doc = Restapi.to_json(params[:resource], params[:method])
 

data/app/views/layouts/restapi/restapi.html.erb

@@ -2,6 +2,7 @@
 <html>
 <head>
   <title>API documentation</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
   <% %w[bundled/bootstrap.min.css 
         application.css
         bundled/prettify.css

data/app/views/restapi/restapis/_params.html.erb

@@ -0,0 +1,22 @@
+<% level ||= 0 %>
+<% col = 255 - level * 5 %>
+<% params.each do |param| %>
+  <tr style='background-color:rgb(<%= "#{col},#{col},#{col}" %>);'>
+    <td>
+      <strong><%= param[:full_name] %> </strong><br>
+      <small>
+        <%= param[:required] ? 'required' : 'optional' %>
+        <%= param[:allow_nil] ? ', nil allowed' : '' %>
+      </small>
+    </td>
+    <td>
+      <%= param[:description].html_safe %>
+      <% unless param[:validator].blank? %>
+        <br>
+        Value: <%= param[:validator] %>
+      <% end %>
+    </td>
+  </tr>
+
+  <%= render(:partial => "params", :locals => {:level => level + 1, :params => param[:params]}) unless param[:params].blank? %>
+<% end %>

data/app/views/restapi/restapis/_params_plain.html.erb

@@ -0,0 +1,16 @@
+<ul>
+  <% params.each do |param| %>
+    <li>
+      <strong><%= param[:name] %> </strong>:
+      <small>
+        <%= param[:required] ? 'required' : 'optional' %>
+        <%= param[:allow_nil] ? ', nil allowed' : '' %>
+        <% if param[:validator] %>
+          [ <%= param[:validator] %> ]
+        <% end %>
+      </small>
+      <%= param[:description].html_safe %>
+    </li>
+    <%= render(:partial => "params_plain", :locals => {:params => param[:params]}) unless param[:params].blank? %>
+  <% end %>
+</ul>

data/app/views/restapi/restapis/index.html.erb

@@ -1,14 +1,14 @@
 <ul class='breadcrumb'>
-  <li class='active'><a href='<%= @doc[:doc_url] %>'><%= @doc[:name] %></a></li>
+  <li class='active'><a href='<%= @doc[:doc_url] %>.html'><%= @doc[:name] %></a></li>
 </ul>
 
 <div><%= @doc[:info].html_safe %></div>
 
 <h1 class='page-header'>Resources</h1>
 
-<% @doc[:resources].each do |key, api| %>
+<% @doc[:resources].sort_by(&:first).each do |key, api| %>
   <h2>
-    <a href='<%= api[:doc_url] %>'><%= api[:name] %></a><br>
+    <a href='<%= api[:doc_url] %>.html'><%= api[:name] %></a><br>
     <small><%= api[:short_description] %></small>
   </h2>
   <table class='table'>
@@ -22,7 +22,7 @@
       <% api[:methods].each do |m| %>
         <% m[:apis].each do |a| %>
           <tr>
-            <td><a href='<%= m[:doc_url] %>'><%= a[:http_method] %> <%= a[:api_url] %></a></td>
+            <td><a href='<%= m[:doc_url] %>.html'><%= a[:http_method] %> <%= a[:api_url] %></a></td>
             <td width='60%'><%= a[:short_description] %></td>
           </tr>
         <% end %>
@@ -33,4 +33,4 @@
 
 <% content_for :restapi_footer do %>
   <%= raw @doc[:copyright] %>
-<% end %>
+<% end %>

data/app/views/restapi/restapis/method.html.erb

@@ -1,10 +1,10 @@
 <ul class='breadcrumb'>
   <li>
-    <a href='<%= @doc[:doc_url] %>'><%= @doc[:name] %></a>
+    <a href='<%= @doc[:doc_url] %>.html'><%= @doc[:name] %></a>
     <span class='divider'>/</span>
   </li>
   <li>
-    <a href='<%= @resource[:doc_url] %>'><%= @resource[:name] %></a>
+    <a href='<%= @resource[:doc_url] %>.html'><%= @resource[:name] %></a>
     <span class='divider'>/</span>
   </li>
   <li class='active'><%= @method[:name] %></li>
@@ -20,6 +20,10 @@
 <% end %>
 
 <div>
+  <% unless @method[:see_url].blank? %>
+    Also see <%= link_to @method[:see], @method[:see_url] %>.
+  <% end %>
+
   <%= raw @method[:full_description] %>
 
   <% unless @method[:examples].blank? %>
@@ -48,7 +52,7 @@
         </tr>
       </thead>
       <tbody>
-        <%= print_nested_params(@method) %>
+        <%= render(:partial => "params", :locals => {:params => @method[:params]}) %>
       </tbody>
     </table>
   <% end %>
@@ -56,4 +60,4 @@
 
 <% content_for :restapi_footer do %>
   <%= raw @doc[:copyright] %>
-<% end %>
+<% end %>

data/app/views/restapi/restapis/plain.html.erb

@@ -0,0 +1,70 @@
+<% @doc[:resources].sort_by(&:first).each do |key, resource| %>
+  <h4><a href='#<%= key %>'><%= resource[:name] %></a></h4>
+  <ul>
+    <% resource[:methods].each do |method| %>
+      <li><a href='#<%= key %>-<%= method[:name] %>'><%= method[:name] %></a></li>
+    <% end %>
+  </ul>
+<% end %>
+
+
+<% @doc[:resources].sort_by(&:first).each do |key, resource| %>
+
+  <hr/>
+
+  <div>
+    <h2 id="<%= key %>">
+      <a href='#<%= key %>'><%= resource[:name] %></a><br>
+      <small><%= raw resource[:short_description] %></small>
+    </h2>
+  </div>
+
+  <% unless resource[:full_description].blank? %>
+    <div><%= raw resource[:full_description] %></div>
+  <% end %>
+
+  <div>
+
+    <% resource[:methods].each do |method| %>
+      <hr/>
+
+      <h3 id="<%= "#{key}-#{method[:name]}" %>">
+      <a href='#<%= key %>'><%= resource[:name] %></a> / <a href='#<%= "#{key}-#{method[:name]}" %>'><%= method[:name] %></a>
+      </h3>
+
+      <div>
+        <% method[:apis].each do |api| %>
+          <h4>
+              <%= api[:http_method] %> <%= api[:api_url] %>
+            <br>
+            <small><%= raw api[:short_description] %></small>
+          </h4>
+        <% end %>
+      </div>
+
+      <div>
+        <%= raw method[:full_description] %>
+        <% unless method[:examples].blank? %>
+          <h4>Examples</h4>
+          <% method[:examples].each do |example| %>
+            <pre class="wiki"><%= example %></pre>
+          <% end %>
+        <% end %>
+
+        <% unless method[:errors].blank? %>
+          <h4>Errors</h4>
+          <% method[:errors].each do |err| %>
+            <%= err.code %>
+            <%= err.description %>
+            <br>
+          <% end %>
+        <% end %>
+
+        <% unless method[:params].blank? %>
+          <h4>Params</h4>
+          <%= render(:partial => "params_plain", :locals => {:params => method[:params]}) %>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+<% end %>

data/app/views/restapi/restapis/resource.html.erb

@@ -1,5 +1,5 @@
 <ul class='breadcrumb'>
-  <li><a href='<%= @doc[:doc_url] %>'><%= @doc[:name] %></a><span class='divider'>/</span></li>
+  <li><a href='<%= @doc[:doc_url] %>.html'><%= @doc[:name] %></a><span class='divider'>/</span></li>
   <li class='active'><%= @resource[:name] %></li>
 </ul>
 
@@ -20,7 +20,7 @@
   <% @resource[:methods].each do |m| %>
     <hr>
     <div class='pull-right small'>
-      <a href='<%= m[:doc_url] %>'> >>> </a>
+      <a href='<%= m[:doc_url] %>.html'> >>> </a>
     </div>
     <div>
       <% m[:apis].each do |api| %>
@@ -36,6 +36,10 @@
       <% end %>
     </div>
     
+    <% unless m[:see_url].blank? %>
+      Also see <%= link_to m[:see], m[:see_url] %>
+    <% end %>
+
     <div id='description-<%= m[:name] %>' class='collapse accordion-body'>
       
       <%= raw m[:full_description] %>
@@ -47,7 +51,14 @@
           <br>
         <% end %>
       <% end %>
-        
+
+      <% unless m[:examples].blank? %>
+        <h3>Examples</h3>
+        <% m[:examples].each do |example| %>
+          <pre><%= example %></pre>
+        <% end %>
+      <% end %>
+
       <% unless m[:params].blank? %>
         <h3>Params</h3>
         <table class='table'>
@@ -58,7 +69,7 @@
             </tr>
           </thead>
           <tbody>
-            <%= print_nested_params(m) %>
+            <%= render(:partial => "params", :locals => {:params => m[:params]}) %>
           </tbody>
         </table>
       <% end %>
@@ -68,4 +79,4 @@
 
 <% content_for :restapi_footer do %>
   <%= raw @doc[:copyright] %>
-<% end %>
+<% end %>

data/app/views/restapi/restapis/static.html.erb

@@ -1,6 +1,4 @@
-<% @doc = doc %>
-
-<% @doc[:resources].each do |key, resource| %>
+<% @doc[:resources].sort_by(&:first).each do |key, resource| %>
   <h4><a href='#<%= key %>'><%= resource[:name] %></a></h4>
   <ul>
     <% resource[:methods].each do |method| %>
@@ -15,7 +13,7 @@
 
 <hr>
 
-<% @doc[:resources].each do |key, resource| %>
+<% @doc[:resources].sort_by(&:first).each do |key, resource| %>
 
   <ul class='breadcrumb'  id='<%= key %>'>
     <li><a href='#'><%= @doc[:name] %></a><span class='divider'>/</span></li>
@@ -89,7 +87,7 @@
               </tr>
             </thead>
             <tbody>
-              <%= print_nested_params(method) %>
+              <%= render(:partial => "params", :locals => {:params => method[:params]}) %>
             </tbody>
           </table>
         <% end %>
@@ -100,4 +98,4 @@
 
 <% content_for :restapi_footer do %>
   <%= raw @doc[:copyright] %>
-<% end %>
+<% end %>

data/lib/restapi.rb

@@ -8,4 +8,5 @@ require "restapi/error_description"
 require "restapi/validator"
 require "restapi/dsl_definition"
 require "restapi/railtie"
-require "restapi/version"
+require 'restapi/extractor'
+require "restapi/version"

data/lib/restapi/application.rb

@@ -1,4 +1,5 @@
 require 'restapi/static_dispatcher'
+require 'yaml'
 
 module Restapi
 
@@ -11,16 +12,16 @@ module Restapi
       end
     end
 
-    attr_accessor :last_api_args, :last_errors, :last_params, :last_description, :last_examples
+    attr_accessor :last_api_args, :last_errors, :last_params, :last_description, :last_examples, :last_see
     attr_reader :method_descriptions, :resource_descriptions
-    
-    def initialize  
+
+    def initialize
       super
       @method_descriptions = Hash.new
       @resource_descriptions = Hash.new
       clear_last
     end
-    
+
     # create new method api description
     def define_method_description(controller, method_name)
       # create new or get existing api
@@ -53,17 +54,25 @@ module Restapi
     def add_example(example)
       @last_examples << example.strip_heredoc
     end
-    
+
     # check if there is some saved description
     def restapi_provided?
       true unless last_api_args.blank?
     end
 
     # get api for given method
-    def get_method_description(resource_name, method_name)
+    #
+    # There are two ways how this method can be used:
+    # 1) Specify both parameters
+    #   resource_name: controller class or string with resource name (plural)
+    #   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")
+    def get_method_description(resource_name, method_name = nil)
       resource_name = get_resource_name(resource_name)
-
-      @method_descriptions[[resource_name, method_name].join('#')]
+      key = method_name.blank? ? resource_name : [resource_name, method_name].join('#')
+      @method_descriptions[key]
     end
     alias :[] :get_method_description
 
@@ -99,27 +108,34 @@ module Restapi
       @last_params = []
       @last_description = nil
       @last_examples = []
+      @last_see = nil
     end
-        
+
     # Return the current description, clearing it in the process.
     def get_description
       desc = @last_description
       @last_description = nil
       desc
     end
-    
+
     def get_errors
       errors = @last_errors.clone
       @last_errors.clear
       errors
     end
-    
+
     def get_api_args
       api_args = @last_api_args.clone
       @last_api_args.clear
       api_args
     end
-    
+
+    def get_see
+      see = @last_see
+      @last_see = nil
+      see
+    end
+
     def get_params
       params = @last_params.clone
       @last_params.clear
@@ -131,9 +147,24 @@ module Restapi
       @last_examples.clear
       examples
     end
-    
+
+    def recorded_examples
+      return @recorded_examples if @recorded_examples
+      tape_file = File.join(Rails.root,"doc","restapi_examples.yml")
+      if File.exists?(tape_file)
+        @recorded_examples = YAML.load_file(tape_file)
+      else
+        @recorded_examples = {}
+      end
+      @recorded_examples
+    end
+
+    def reload_examples
+      @recorded_examples = nil
+    end
+
     def to_json(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
@@ -150,26 +181,45 @@ module Restapi
           :name => Restapi.configuration.app_name,
           :info => Restapi.configuration.app_info,
           :copyright => Restapi.configuration.copyright,
-          :doc_url => "#{ENV["RAILS_RELATIVE_URL_ROOT"]}#{Restapi.configuration.doc_base_url}",
+          :doc_url => Restapi.full_url(""),
           :api_url => Restapi.configuration.api_base_url,
           :resources => _resources
         }
       }
     end
 
+    def api_controllers_paths
+      Dir[Restapi.configuration.api_controllers_matcher]
+    end
+
     def reload_documentation
-      Dir[Restapi.configuration.api_controllers_matcher].each {|f|  load f}
+      reload_examples
+      api_controllers_paths.each do |f|
+        load_controller_from_file f
+      end
+    end
+
+    # Is there a reason to interpret the DSL for this run?
+    # with specific setting for some environment there is no reason the dsl
+    # should be interpreted (e.g. no validations and doc from cache)
+    def active_dsl?
+      Restapi.configuration.validate? || ! Restapi.configuration.use_cache? || Restapi.configuration.force_dsl?
     end
 
     private
 
-      def get_resource_name(klass)
-        if klass.class == String
-          klass
-        elsif klass.class == Class && ActionController::Base.descendants.include?(klass)
-          klass.controller_name
-        end
+    def get_resource_name(klass)
+      if klass.class == String
+        klass
+      elsif klass.respond_to?(:controller_name)
+        klass.controller_name
       end
+    end
+
+    def load_controller_from_file(controller_file)
+      controller_class_name = controller_file.gsub(/\A.*\/app\/controllers\//,"").gsub(/\.\w*\Z/,"").camelize
+      controller_class_name.constantize
+    end
 
   end
 end