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

apipie-rails 0.1.3 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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)