RubyGems - apipie-rails - Versions diffs - 0.1.3 → 0.2.0 - Mend

apipie-rails 0.1.3 → 0.2.0

Files changed (38) hide show

data/.travis.yml +1 -2
data/CHANGELOG.md +26 -0
data/README.rst +94 -3
data/app/controllers/apipie/apipies_controller.rb +28 -10
data/app/views/apipie/apipies/_disqus.html.erb +4 -2
data/app/views/apipie/apipies/_languages.erb +6 -0
data/app/views/apipie/apipies/_method_detail.erb +7 -7
data/app/views/apipie/apipies/_params.html.erb +2 -2
data/app/views/apipie/apipies/_params_plain.html.erb +2 -2
data/app/views/apipie/apipies/apipie_404.html.erb +7 -4
data/app/views/apipie/apipies/getting_started.html.erb +5 -3
data/app/views/apipie/apipies/index.html.erb +7 -6
data/app/views/apipie/apipies/method.html.erb +4 -2
data/app/views/apipie/apipies/plain.html.erb +3 -3
data/app/views/apipie/apipies/resource.html.erb +3 -2
data/app/views/apipie/apipies/static.html.erb +7 -7
data/app/views/layouts/apipie/apipie.html.erb +1 -1
data/config/locales/en.yml +27 -0
data/lib/apipie-rails.rb +7 -0
data/lib/apipie/apipie_module.rb +5 -2
data/lib/apipie/application.rb +27 -16
data/lib/apipie/configuration.rb +6 -1
data/lib/apipie/extractor.rb +35 -26
data/lib/apipie/extractor/recorder.rb +9 -5
data/lib/apipie/extractor/writer.rb +36 -7
data/lib/apipie/method_description.rb +6 -6
data/lib/apipie/param_description.rb +9 -4
data/lib/apipie/resource_description.rb +5 -5
data/lib/apipie/routing.rb +1 -1
data/lib/apipie/version.rb +1 -1
data/lib/generators/apipie/install/templates/initializer.rb.erb +1 -1
data/lib/tasks/apipie.rake +89 -47
data/spec/dummy/doc/apipie_examples.json +1 -0
data/spec/lib/extractor/middleware_spec.rb +21 -0
data/spec/lib/extractor/writer_spec.rb +76 -0
metadata +10 -5
data/Gemfile.rails30 +0 -5
data/spec/dummy/doc/apipie_examples.yml +0 -28

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

@@ -7,6 +7,7 @@
     <%= @resource[:name] %>
     <% if @resource[:version] %><% end %>
   </li>
+  <%= render(:partial => "languages", :locals => {:doc_url => @resource[:doc_url]}) %>
 </ul>
 <div class='page-header'>
@@ -62,6 +63,6 @@
   <% end %>
 </div>
-<% content_for :apipie_footer do %>
-  <%= raw @doc[:copyright] %>
+<% unless content_for(:apipie_footer) == @doc[:copyright] %>
+  <%= content_for :apipie_footer, raw(@doc[:copyright]) %>
 <% end %>

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

@@ -62,14 +62,14 @@
       <div>
         <%= raw method[:full_description] %>
         <% unless method[:examples].blank? %>
-          <h2>Examples</h2>
+          <h2><%= t('apipie.examples') %></h2>
           <% method[:examples].each do |example| %>
             <pre><%= example %></pre>
           <% end %>
         <% end %>
         <% unless method[:errors].blank? %>
-          <h2>Errors</h2>
+          <h2><%= t('apipie.errors') %></h2>
           <% method[:errors].each do |err| %>
             <%= err[:code] %>
             <%= err[:description] %>
@@ -79,12 +79,12 @@
         <% end %>
         <% unless method[:params].blank? %>
-          <h2>Params</h2>
+          <h2><%= t('apipie.params') %></h2>
           <table class='table'>
             <thead>
               <tr>
-                <th>Param name</th>
-                <th>Description</th>
+                <th><%= t('apipie.param_name') %></th>
+                <th><%= t('apipie.description') %></th>
               </tr>
             </thead>
             <tbody>
@@ -97,6 +97,6 @@
   </div>
 <% end %>
-<% content_for :apipie_footer do %>
-  <%= raw @doc[:copyright] %>
+<% unless content_for(:apipie_footer) == @doc[:copyright] %>
+  <%= content_for :apipie_footer, raw(@doc[:copyright]) %>
 <% end %>

data/app/views/layouts/apipie/apipie.html.erb CHANGED Viewed

@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html>
 <head>
-  <title>API documentation</title>
+  <title><%= t('apipie.api_documentation') %></title>
   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
   <%= Apipie.include_stylesheets %>
   <link type='text/css' rel='stylesheet' href='<%= Apipie.full_url("stylesheets/application.css")%>'/>

data/config/locales/en.yml ADDED Viewed

@@ -0,0 +1,27 @@
+en:
+    apipie:
+        resources: Resources
+        resource: Resource
+        description: Description
+        no_docs_found: No documentation found
+        no_docs_found_descr: We have not found any documentation for your API.
+        follow_instructions_html: Follow %{href} on how to describe your controllers.
+        follow_instructions_href: further instructions
+        oops: Oops!!
+        resource_not_found_html: Resource %{res} not found.
+        method_not_found_html: Method %{method} not found for resource %{resource}.
+        goto_homepage_html: Try going to %{href}
+        goto_homepage_href: "%{app_name} API documentation homepage"
+        required: required
+        optional: optional
+        nil_allowed: nil allowed
+        param_name: Param name
+        params: Params
+        examples: Examples
+        metadata: Metadata
+        errors: Errors
+        supported_formats: Supported Formats
+        enable_javascript_html: Please enable JavaScript to view the %{comments_href}.
+        comments_powered_by_disqus: comments powered by %{disqus}
+        api_documentation: API documentation

data/lib/apipie-rails.rb CHANGED Viewed

@@ -1,3 +1,6 @@
+require 'i18n'
+require 'active_support/hash_with_indifferent_access'
 require "apipie/routing"
 require "apipie/markup"
 require "apipie/apipie_module"
@@ -13,3 +16,7 @@ require "apipie/validator"
 require "apipie/railtie"
 require 'apipie/extractor'
 require "apipie/version"
+if Rails.version.start_with?("3.0")
+  warn 'Warning: apipie-rails is not going to support Rails 3.0 anymore in future versions'
+end

data/lib/apipie/apipie_module.rb CHANGED Viewed

@@ -8,9 +8,9 @@ module Apipie
     @application ||= Apipie::Application.new
   end
-  def self.to_json(version = nil, resource_name = nil, method_name = nil)
+  def self.to_json(version = nil, resource_name = nil, method_name = nil, lang = nil)
     version ||= Apipie.configuration.default_version
-    app.to_json(version, resource_name, method_name)
+    app.to_json(version, resource_name, method_name, lang)
   end
   # all calls delegated to Apipie::Application instance
@@ -59,4 +59,7 @@ module Apipie
     version && self.configuration.api_base_url.has_key?(version)
   end
+  def self.record(record)
+    Apipie::Extractor.start record
+  end
 end

data/lib/apipie/application.rb CHANGED Viewed

@@ -207,25 +207,14 @@ module Apipie
     def recorded_examples
       return @recorded_examples if @recorded_examples
-      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 YAML.respond_to?(:safe_load_file) && defined?(SafeYAML)
-          @recorded_examples = YAML.load_file(tape_file, :safe=>false)
-        else
-          @recorded_examples = YAML.load_file(tape_file)
-        end
-      else
-        @recorded_examples = {}
-      end
-      @recorded_examples
+      @recorded_examples = Apipie::Extractor::Writer.load_recorded_examples
     end
     def reload_examples
       @recorded_examples = nil
     end
-    def to_json(version, resource_name, method_name)
+    def to_json(version, resource_name, method_name, lang)
       return unless resource_descriptions.has_key?(version)
@@ -233,11 +222,11 @@ module Apipie
         # take just resources which have some methods because
         # we dont want to show eg ApplicationController as resource
         resource_descriptions[version].inject({}) do |result, (k,v)|
-          result[k] = v.to_json unless v._methods.blank?
+          result[k] = v.to_json(nil, lang) unless v._methods.blank?
           result
         end
       else
-        [@resource_descriptions[version][resource_name].to_json(method_name)]
+        [@resource_descriptions[version][resource_name].to_json(method_name, lang)]
       end
       url_args = Apipie.configuration.version_in_url ? version : ''
@@ -245,7 +234,7 @@ module Apipie
       {
         :docs => {
           :name => Apipie.configuration.app_name,
-          :info => Apipie.app_info(version),
+          :info => translate(Apipie.app_info(version), lang),
           :copyright => Apipie.configuration.copyright,
           :doc_url => Apipie.full_url(url_args),
           :api_url => Apipie.api_base_url(version),
@@ -259,12 +248,18 @@ module Apipie
     end
     def reload_documentation
+      # don't load translated strings, we'll translate them later
+      old_locale = locale
+      locale = Apipie.configuration.default_locale
       rails_mark_classes_for_reload
       api_controllers_paths.each do |f|
         load_controller_from_file f
       end
       @checksum = nil if Apipie.configuration.update_checksum
+      locale = old_locale
     end
     def compute_checksum
@@ -311,6 +306,22 @@ module Apipie
       end
     end
+    def locale
+      Apipie.configuration.locale.call(nil) if Apipie.configuration.locale
+    end
+    def locale=(locale)
+      Apipie.configuration.locale.call(locale) if Apipie.configuration.locale
+    end
+    def translate(str, locale)
+      if Apipie.configuration.translate
+        Apipie.configuration.translate.call(str, locale)
+      else
+        str
+      end
+    end
     private
     def version_prefix(klass)

data/lib/apipie/configuration.rb CHANGED Viewed

@@ -6,7 +6,7 @@ module Apipie
       :default_version, :debug, :version_in_url, :namespaced_resources,
       :validate, :validate_value, :validate_presence, :authenticate, :doc_path,
       :show_all_examples, :process_params, :update_checksum, :checksum_path,
-      :link_extension
+      :link_extension, :record, :languages, :translate, :locale, :default_locale
     alias_method :validate?, :validate
     alias_method :required_by_default?, :required_by_default
@@ -141,6 +141,11 @@ module Apipie
       @checksum_path = [@doc_base_url, '/api/']
       @update_checksum = false
       @link_extension = ".html"
+      @record = false
+      @languages = []
+      @default_locale = 'en'
+      @locale = lambda { |locale| @default_locale }
+      @translate = lambda { |str, locale| str }
     end
   end
 end

data/lib/apipie/extractor.rb CHANGED Viewed

@@ -7,17 +7,17 @@ require 'apipie/extractor/writer'
 require 'apipie/extractor/collector'
 class Apipie::Railtie
-  if ENV["APIPIE_RECORD"]
-    initializer 'apipie.extractor' do |app|
-      ActiveSupport.on_load :action_controller do
-        before_filter do |controller|
+  initializer 'apipie.extractor' do |app|
+    ActiveSupport.on_load :action_controller do
+      before_filter do |controller|
+        if Apipie.configuration.record
           Apipie::Extractor.call_recorder.analyse_controller(controller)
         end
       end
-      app.middleware.use ::Apipie::Extractor::Recorder::Middleware
-      ActionController::TestCase::Behavior.instance_eval do
-        include Apipie::Extractor::Recorder::FunctionalTestRecording
-      end
+    end
+    app.middleware.use ::Apipie::Extractor::Recorder::Middleware
+    ActionController::TestCase::Behavior.instance_eval do
+      include Apipie::Extractor::Recorder::FunctionalTestRecording
     end
   end
 end
@@ -28,6 +28,29 @@ module Apipie
     class << self
+      def start(record)
+        Apipie.configuration.record = record
+        Apipie.configuration.force_dsl = true
+      end
+      def finish
+        record_params, record_examples = false, false
+        case Apipie.configuration.record
+        when "params"   then record_params = true
+        when "examples" then record_examples = true
+        when "all"      then record_params = true, record_examples = true
+        end
+        if record_examples
+          puts "Writing examples to a file"
+          write_examples
+        end
+        if record_params
+          puts "Updating auto-generated documentation"
+          write_docs
+        end
+      end
       def logger
         Rails.logger
       end
@@ -144,28 +167,14 @@ module Apipie
           end
         end
       end
     end
   end
 end
 if ENV["APIPIE_RECORD"]
-  Apipie.configuration.force_dsl = true
-  at_exit do
-    record_params, record_examples = false, false
-    case ENV["APIPIE_RECORD"]
-    when "params"   then record_params = true
-    when "examples" then record_examples = true
-    when "all"      then record_params = true, record_examples = true
-    end
+  Apipie::Extractor.start ENV["APIPIE_RECORD"]
+end
-    if record_examples
-      puts "Writing examples to a file"
-      Apipie::Extractor.write_examples
-    end
-    if record_params
-      puts "Updating auto-generated documentation"
-      Apipie::Extractor.write_docs
-    end
-  end
+at_exit do
+  Apipie::Extractor.finish
 end

data/lib/apipie/extractor/recorder.rb CHANGED Viewed

@@ -89,7 +89,11 @@ module Apipie
         end
         def call(env)
-          analyze(env) do
+          if Apipie.configuration.record
+            analyze(env) do
+              @app.call(env)
+            end
+          else
             @app.call(env)
           end
         end
@@ -112,15 +116,15 @@ module Apipie
         def process_with_api_recording(*args) # action, parameters = nil, session = nil, flash = nil, http_method = 'GET')
           ret = process_without_api_recording(*args)
-          Apipie::Extractor.call_recorder.analyze_functional_test(self)
-          Apipie::Extractor.call_finished
+          if Apipie.configuration.record
+            Apipie::Extractor.call_recorder.analyze_functional_test(self)
+            Apipie::Extractor.call_finished
+          end
           ret
         ensure
           Apipie::Extractor.clean_call_recorder
         end
       end
     end
   end
 end

data/lib/apipie/extractor/writer.rb CHANGED Viewed

@@ -6,15 +6,11 @@ module Apipie
       def initialize(collector)
         @collector = collector
-        @examples_file = File.join(Rails.root, "doc", "apipie_examples.yml")
       end
       def write_examples
         merged_examples = merge_old_new_examples
-        FileUtils.mkdir_p(File.dirname(@examples_file))
-        File.open(@examples_file, "w") do |f|
-          f << YAML.dump(OrderedHash[*merged_examples.sort_by(&:first).flatten(1)])
-        end
+        self.class.write_recorded_examples(merged_examples)
       end
       def write_docs
@@ -40,8 +36,38 @@ module Apipie
         logger.warn("REST_API: Couldn't find action #{action} in #{controller}")
       end
+      def self.write_recorded_examples(examples)
+        examples_file = self.examples_file
+        FileUtils.mkdir_p(File.dirname(examples_file))
+        File.open(examples_file, "w") do |f|
+          f << JSON.pretty_generate(OrderedHash[*examples.sort_by(&:first).flatten(1)])
+        end
+      end
+      def self.load_recorded_examples
+        examples_file = self.examples_file
+        if File.exists?(examples_file)
+          return load_json_examples
+        end
+        return {}
+      end
+      def self.examples_file
+        File.join(Rails.root,"doc","apipie_examples.json")
+      end
       protected
+      def self.load_json_examples
+        examples = JSON.load(IO.read(examples_file))
+        return {} if examples.nil?
+        examples.each do |method, records|
+          records.each do |record|
+            record["verb"] = record["verb"].to_sym if record["verb"]
+          end
+        end
+      end
       def desc_to_s(description)
         "#{description[:controller].name}##{description[:action]}"
       end
@@ -61,9 +87,13 @@ module Apipie
         return ordered_call
       end
+      def load_recorded_examples
+        self.class.load_recorded_examples
+      end
       def merge_old_new_examples
         new_examples = self.load_new_examples
-        old_examples = self.load_old_examples
+        old_examples = self.load_recorded_examples
         merged_examples = []
         (new_examples.keys + old_examples.keys).uniq.each do |key|
           if new_examples.has_key?(key)
@@ -364,6 +394,5 @@ module Apipie
         end
       end
     end
   end
 end

data/lib/apipie/method_description.rb CHANGED Viewed

@@ -108,12 +108,12 @@ module Apipie
       return path
     end
-    def method_apis_to_json
+    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 => api.short_description
+          :short_description => Apipie.app.translate(api.short_description, lang)
         }
       end
     end
@@ -126,15 +126,15 @@ module Apipie
       @formats || @resource._formats
     end
-    def to_json
+    def to_json(lang=nil)
       {
         :doc_url => doc_url,
         :name => @method,
-        :apis => method_apis_to_json,
+        :apis => method_apis_to_json(lang),
         :formats => formats,
-        :full_description => @full_description,
+        :full_description => Apipie.app.translate(@full_description, lang),
         :errors => errors.map(&:to_json),
-        :params => params_ordered.map(&:to_json).flatten,
+        :params => params_ordered.map{ |param| param.to_json(lang) }.flatten,
         :examples => @examples,
         :metadata => @metadata,
         :see => see.map(&:to_json)