apipie-rails 0.0.24 → 0.1.0

data/app/views/apipie/apipies/_metadata.erb

@@ -0,0 +1 @@
+<pre class="prettyprint lang-yaml"><%= meta.to_yaml.gsub(/---\n/, "") %></pre>

data/app/views/apipie/apipies/_method_detail.erb

@@ -0,0 +1,46 @@
+<%= raw method[:full_description] %>
+
+<% unless method[:formats].blank? %>
+  <%= heading('Supported Formats', h_level) %>
+  <%= method[:formats].join(', ') %>
+<% end %>
+
+<% unless method[:errors].blank? %>
+  <%= heading('Errors', h_level) %>
+  <% method[:errors].each do |err| %>
+    <%= err[:code] %>
+    <%= err[:description] %>
+    <br>
+    <% unless err[:metadata].blank? %>
+      Metadata:
+      <pre class="prettyprint lang-yaml"><%= err[:metadata].to_yaml %></pre>
+    <% end %>
+  <% end %>
+<% end %>
+
+<% unless method[:metadata].blank? %>
+  <%= heading('Metadata', h_level) %>
+  <%= render(:partial => "metadata", :locals => {:meta => method[:metadata]}) %>
+<% end %>
+
+<% unless method[:examples].blank? %>
+  <%= heading('Examples', h_level) %>
+  <% method[:examples].each do |example| %>
+    <pre class="prettyprint"><%= example %></pre>
+  <% end %>
+<% end %>
+
+<% unless method[:params].blank? %>
+  <%= heading('Params', h_level) %>
+  <table class='table'>
+    <thead>
+      <tr>
+        <th>Param name</th>
+        <th>Description</th>
+      </tr>
+    </thead>
+    <tbody>
+      <%= render(:partial => "params", :locals => {:params => method[:params]}) %>
+    </tbody>
+  </table>
+<% end %>

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

@@ -1,6 +1,10 @@
 <% level ||= 0 %>
 <% col = 255 - level * 5 %>
 <% params.each do |param| %>
+  <% if !param[:show] %>
+    <%= render(:partial => "params", :locals => {:level => level, :params => param[:params]}) unless param[:params].blank? %>
+    <% next %>
+  <% end %>
   <tr style='background-color:rgb(<%= "#{col},#{col},#{col}" %>);'>
     <td>
       <strong><%= param[:full_name] %> </strong><br>
@@ -15,7 +19,15 @@
         <br>
         Value: <%= param[:validator] %>
       <% end %>
+
+      <% unless param[:metadata].blank? %>
+        <br>
+        Metadata:
+        <%= render(:partial => "metadata", :locals => {:meta => param[:metadata]}) %>
+      <% end %>
+
     </td>
+
   </tr>
 
   <%= render(:partial => "params", :locals => {:level => level + 1, :params => param[:params]}) unless param[:params].blank? %>

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

@@ -1,5 +1,9 @@
 <ul>
   <% params.each do |param| %>
+    <% if !param[:show] %>
+      <%= render(:partial => "params_plain", :locals => {:params => param[:params]}) unless param[:params].blank? %>
+      <% next %>
+    <% end %>
     <li>
       <strong><%= param[:name] %> </strong>:
       <small>

data/app/views/apipie/apipies/apipie_checksum.json.erb

@@ -0,0 +1 @@
+{ "checksum": "<%= raw Apipie.checksum %>" }

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

@@ -27,43 +27,7 @@
     Also see <%= @method[:see].map { |s| link_to(s[:description], "#{s[:link]}.html") }.to_sentence.html_safe %>.
   <% end %>
 
-  <%= raw @method[:full_description] %>
-
-  <% unless @method[:examples].blank? %>
-    <h2>Examples</h2>
-    <% @method[:examples].each do |example| %>
-      <pre class="prettyprint"><%= example %></pre>
-    <% end %>
-  <% end %>
-
-  <% unless @method[:formats].blank? %>
-    <h2>Supported Formats</h2>
-    <%= @method[:formats].join(', ') %>
-  <% end %>
-
-  <% unless @method[:errors].blank? %>
-    <h2>Errors</h2>
-    <% @method[:errors].each do |err| %>
-      <%= err[:code] %>
-      <%= err[:description] %>
-      <br>
-    <% end %>
-  <% end %>
-
-  <% unless @method[:params].blank? %>
-    <h2>Params</h2>
-    <table class='table'>
-      <thead>
-        <tr>
-          <th>Param name</th>
-          <th>Description</th>
-        </tr>
-      </thead>
-      <tbody>
-        <%= render(:partial => "params", :locals => {:params => @method[:params]}) %>
-      </tbody>
-    </table>
-  <% end %>
+  <%= render(:partial => "method_detail", :locals => {:method => @method, :h_level => 2}) %>
 </div>
 
 <% content_for :apipie_footer do %>

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

@@ -56,6 +56,7 @@
           <% method[:errors].each do |err| %>
             <%= err[:code] %>
             <%= err[:description] %>
+            <%= render(:partial => "metadata", :locals => {:meta => err[:metadata]}) %>
             <br>
           <% end %>
         <% end %>

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

@@ -21,6 +21,11 @@
   <div><%= raw @resource[:full_description] %></div>
 <% end %>
 
+<% unless @resource[:metadata].blank? %>
+  <h2>Metadata</h2>
+  <%= render(:partial => "metadata", :locals => {:meta => @resource[:metadata]}) %>
+<% end %>
+
 <% unless @resource[:formats].blank? %>
   <h2>Supported Formats</h2>
   <%= @resource[:formats].join(', ') %>
@@ -52,43 +57,7 @@
     <% end %>
 
     <div id='description-<%= m[:name] %>' class='collapse accordion-body'>
-      <%= raw m[:full_description] %>
-
-      <% unless m[:formats].blank? %>
-        <h3>Supported Formats</h3>
-        <%= m[:formats].join(', ') %>
-      <% end %>
-
-      <% unless m[:errors].blank? %>
-        <h3>Errors</h3>
-        <% m[:errors].each do |err| %>
-          <%= err[:code] %>
-          <%= err[:description] %>
-          <br>
-        <% end %>
-      <% end %>
-
-      <% unless m[:examples].blank? %>
-        <h3>Examples</h3>
-        <% m[:examples].each do |example| %>
-          <pre class="prettyprint"><%= example %></pre>
-        <% end %>
-      <% end %>
-
-      <% unless m[:params].blank? %>
-        <h3>Params</h3>
-        <table class='table'>
-          <thead>
-            <tr>
-              <th>Param name</th>
-              <th>Description</th>
-            </tr>
-          </thead>
-          <tbody>
-            <%= render(:partial => "params", :locals => {:params => m[:params]}) %>
-          </tbody>
-        </table>
-      <% end %>
+      <%= render(:partial => "method_detail", :locals => {:method => m, :h_level => 3}) %>
     </div>
   <% end %>
 </div>

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

@@ -73,6 +73,7 @@
           <% method[:errors].each do |err| %>
             <%= err[:code] %>
             <%= err[:description] %>
+            <%= render(:partial => "metadata", :locals => {:meta => err[:metadata]}) %>
             <br>
           <% end %>
         <% end %>

data/lib/apipie/application.rb

@@ -1,5 +1,7 @@
 require 'apipie/static_dispatcher'
 require 'yaml'
+require 'digest/md5'
+require 'json'
 
 module Apipie
 
@@ -208,8 +210,8 @@ module Apipie
       tape_file = File.join(Rails.root,"doc","apipie_examples.yml")
       if File.exists?(tape_file)
         #if SafeYAML gem is enabled, it will load examples as an array of Hash, instead of hash
-        if defined? SafeYAML
-          @recorded_examples = YAML.load_file(tape_file, :safe=>false)
+        if YAML.respond_to?(:safe_load_file) && defined?(SafeYAML)
+          @recorded_examples = SafeYAML.load_file(tape_file, :safe=>false)
         else
           @recorded_examples = YAML.load_file(tape_file)
         end
@@ -264,6 +266,18 @@ module Apipie
       api_controllers_paths.each do |f|
         load_controller_from_file f
       end
+      @checksum = compute_checksum if Apipie.configuration.update_checksum
+    end
+
+    def compute_checksum
+      all_docs = Apipie.available_versions.inject({}) do |all, version|
+        all.update(version => Apipie.to_json(version))
+      end
+      Digest::MD5.hexdigest(JSON.dump(all_docs))
+    end
+
+    def checksum
+      @checksum ||= compute_checksum
     end
 
     # Is there a reason to interpret the DSL for this run?

data/lib/apipie/configuration.rb

@@ -4,8 +4,8 @@ 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, :authenticate, :doc_path,
+      :show_all_examples, :process_params, :update_checksum, :checksum_path
 
     alias_method :validate?, :validate
     alias_method :required_by_default?, :required_by_default
@@ -36,6 +36,9 @@ module Apipie
     end
     alias_method :validate_presence?, :validate_presence
 
+    def process_value?
+      @process_params
+    end
     # set to true if you want to use pregenerated documentation cache and avoid
     # generating the documentation on runtime (usefull for production
     # environment).
@@ -124,6 +127,9 @@ module Apipie
       @version_in_url = true
       @namespaced_resources = false
       @doc_path = "doc"
+      @process_params = false
+      @checksum_path = [@doc_base_url, '/api/']
+      @update_checksum = false
     end
   end
 end

data/lib/apipie/dsl_definition.rb

@@ -6,7 +6,7 @@ module Apipie
   module DSL
 
     module Base
-      attr_reader :apipie_resource_descriptions
+      attr_reader :apipie_resource_descriptions, :api_params
 
       private
 
@@ -29,7 +29,8 @@ module Apipie
          :examples          => [],
          :see               => [],
          :formats           => nil,
-         :api_versions      => []
+         :api_versions      => [],
+         :meta              => nil
        }
       end
     end
@@ -76,7 +77,7 @@ module Apipie
       # Example:
       #   api :GET, "/resource_route", "short description",
       #
-      def api(method, path, desc = nil) #:doc:
+      def api(method, path, desc = nil, options={}) #:doc:
         return unless Apipie.active_dsl?
         _apipie_dsl_data[:api_args] << [method, path, desc]
       end
@@ -164,20 +165,27 @@ module Apipie
         _apipie_dsl_data[:formats] = formats
       end
 
+      # Describe additional metadata
+      #
+      #   meta :author => { :name => 'John', :surname => 'Doe' }
+      def meta(meta) #:doc:
+        _apipie_dsl_data[:meta] = meta
+      end
+
 
       # Describe possible errors
       #
       # Example:
-      #   error :desc => "speaker is sleeping", :code => 500
+      #   error :desc => "speaker is sleeping", :code => 500, :meta => [:some, :more, :data]
       #   error 500, "speaker is sleeping"
       #   def hello_world
       #     return 500 if self.speaker.sleeping?
       #     puts "hello world"
       #   end
       #
-      def error(*args) #:doc:
+      def error(code_or_options, desc=nil, options={}) #:doc:
         return unless Apipie.active_dsl?
-        _apipie_dsl_data[:errors] << args
+        _apipie_dsl_data[:errors] << [code_or_options, desc, options]
       end
 
       def _apipie_define_validators(description)
@@ -186,6 +194,8 @@ module Apipie
 
           old_method = instance_method(description.method)
 
+
+          # @todo we should use before_filter
           define_method(description.method) do |*args|
 
             if Apipie.configuration.validate_presence?
@@ -202,6 +212,15 @@ module Apipie
               end
             end
 
+            if Apipie.configuration.process_value?
+              @api_params = {}
+
+              description.params.each do |_, param|
+                # params processing
+                @api_params[param.as] = param.process_value(params[:"#{param.name}"]) if params.has_key?(param.name)
+              end
+            end
+
             # run the original method code
             old_method.bind(self).call(*args)
           end

data/lib/apipie/error_description.rb

@@ -2,22 +2,34 @@ module Apipie
 
   class ErrorDescription
 
-    attr_reader :code, :description
+    attr_reader :code, :description, :metadata
 
-    def initialize(args)
-      if args.first.is_a? Hash
-        args = args.first
-      elsif args.count == 2
-        args = {:code => args.first, :description => args.second}
+    def self.from_dsl_data(args)
+      code_or_options, desc, options = args
+      Apipie::ErrorDescription.new(code_or_options,
+                                   desc,
+                                   options)
+    end
+
+    def initialize(code_or_options, desc=nil, options={})
+      if code_or_options.is_a? Hash
+        code_or_options.symbolize_keys!
+        @code = code_or_options[:code]
+        @metadata = code_or_options[:meta]
+        @description = code_or_options[:desc] || code_or_options[:description]
       else
-        raise ArgumentError "ApipieError: Bad use of error method."
+        @code = code_or_options
+        @metadata = options[:meta]
+        @description = desc
       end
-      @code = args[:code] || args['code']
-      @description = args[:desc] || args[:description] || args['desc'] || args['description']
     end
 
     def to_json
-      {:code => code, :description => description}
+      {
+        :code => code,
+        :description => description,
+        :metadata => metadata
+      }
     end
 
   end

data/lib/apipie/extractor.rb

@@ -86,7 +86,8 @@ module Apipie
           controller_path, action = route[:controller], route[:action]
           next unless controller_path && action
 
-          controller = "#{controller_path}_controller".camelize
+          controller_path = controller_path.split('::').map(&:camelize).join('::')
+          controller = "#{controller_path}Controller"
 
           path = if /^#{Regexp.escape(api_prefix)}(.*)$/ =~ route[:path]
                    $1.sub!(/\(\.:format\)$/,"")

data/lib/apipie/extractor/writer.rb

@@ -84,7 +84,9 @@ module Apipie
             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) }
+            if Apipie.configuration.show_all_examples
+              show_in_doc = 1
+            elsif call[:versions].any? { |v| ! showed_in_versions.include?(v) }
               call[:versions].each { |v| showed_in_versions << v }
               show_in_doc = 1
             else
@@ -99,11 +101,11 @@ module Apipie
 
       def load_old_examples
         if File.exists?(@examples_file)
-           if defined? SafeYAML
-              return YAML.load_file(@examples_file, :safe=>false)
-            else
-              return YAML.load_file(@examples_file)
-            end
+          if defined? SafeYAML
+            return YAML.load_file(@examples_file, :safe=>false)
+          else
+            return YAML.load_file(@examples_file)
+          end
         end
         return {}
       end