apipie-rails 0.1.3 → 0.2.0

data/.travis.yml

@@ -2,9 +2,8 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0.0
-  - 2.1.0
+  - 2.1.1
 gemfile:
-  - Gemfile.rails30
   - Gemfile.rails32
   - Gemfile.rails40
   - Gemfile.rails41

data/CHANGELOG.md

@@ -2,6 +2,30 @@
  Changelog
 ===========
 
+v0.2.0
+------
+
+This is not full backward compatible release, as the format of storing
+examples changed from YAML to JSON: the default location is at
+`doc/apipie_examples.json`. The migration should be as easy as
+running:
+
+```
+rake apipie:convert_examples
+```
+
+Also please not Rails 3.0 support was deprecated and the compatibility
+wont be tracked anymore in next releases.
+
+* dump examples as json
+  [#125](https://github.com/Apipie/apipie-rails/pull/125) [@johanneswuerbach][]
+* support for localized API documentation
+  [#232](https://github.com/Apipie/apipie-rails/pull/232) [@mbacovsky][]
+* configuration option to always record examples
+  [#239](https://github.com/Apipie/apipie-rails/pull/239) [@arathunku][]
+* deprecate Rails 3.0
+  [#241](https://github.com/Apipie/apipie-rails/pull/241) [@iNecas][]
+
 v0.1.3
 ------
 
@@ -119,3 +143,5 @@ v0.0.15
 [@mkrajewski]: https://github.com/mkrajewski
 [@iNecas]: https://github.com/iNecas
 [@clamoris]: https://github.com/clamoris
+[@arathunku]: https://github.com/arathunku
+[@johanneswuerbach]: https://github.com/johanneswuerbach

data/README.rst

@@ -554,7 +554,25 @@ show_all_examples
 
 link_extension
   The extension to use for API pages ('.html' by default).  Link extensions
-  in static API docs cannot be changed from '.html'. 
+  in static API docs cannot be changed from '.html'.
+
+languages
+  List of languages API documentation should be translated into. Empty list by default.
+
+default_locale
+  Locale used for generating documentation when no specific locale is set.
+  Set to 'en' by default.
+
+locale
+  Pass locale setter/getter
+
+.. code:: ruby
+
+    config.locale = lambda { |loc| loc ? FastGettext.set_locale(loc) : FastGettext.locale }
+
+translate
+  Pass proc to translate strings using localization library your project uses.
+  For example see `Localization`_
 
 Example:
 
@@ -863,6 +881,79 @@ For inspiration this is how Textile markup usage looks like:
      end
    end
 
+============
+Localization
+============
+
+Apipie has support for localized API documentation in both formats (JSON and HTML).
+Apipie uses the library I18n for localization of itself.
+Check ``config/locales`` directory for available translation.
+
+Major part of strings in the documentation comes from the API.
+As prefferences about localization libraries differs among project, Apipie needs to know how to set locale for your project
+and how to translate a string using library your project use. That can be done using lambdas in configuration.
+
+Sample configuration when your project use FastGettext
+
+
+.. code:: ruby
+
+   Apipie.configure do |config|
+    ...
+    config.languages = ['en', 'cs']
+    config.default_locale = 'en'
+    config.locale = lambda { |loc| loc ? FastGettext.set_locale(loc) : FastGettext.locale }
+    config.translate = lambda do |str, loc|
+      old_loc = FastGettext.locale
+      FastGettext.set_locale(loc)
+      trans = _(str)
+      FastGettext.set_locale(old_loc)
+      trans
+    end
+   end
+
+And the strings in API documentation needs to be marked with the ``N_()`` function
+
+.. code:: ruby
+
+  api :GET, "/users/:id", N_("Show user profile")
+  param :session, String, :desc => N_("user is logged in"), :required => true
+
+
+
+When your project use I18n, localization related configuration could look like as follows
+
+.. code:: ruby
+
+   Apipie.configure do |config|
+    ...
+    config.languages = ['en', 'cs']
+    config.default_locale = 'en'
+    config.locale = lambda { |loc| loc ? I18n.locale = loc : I18n.locale }
+    config.translate = lambda do |str, loc|
+      old_loc = I18n.locale
+      I18n.locale = loc
+      trans = I18n.t(str)
+      I18n.locale = old_loc
+      trans
+    end
+   end
+
+And the strings in API documentation needs to be in the form of translation keys
+
+.. code:: ruby
+
+  api :GET, "/users/:id", "show_user_profile"
+  param :session, String, :desc => "user_is_logged_in", :required => true
+
+
+The localized versions of the documentation are distinguished by languge in the filename.
+E.g. ``doc/apidoc/apidoc.cs.html`` is static documentation in the Czech language.
+If the language is missing, e.g. ``doc/apidoc/apidoc.html``,
+the documentation is localized with the ``default_locale``.
+
+The dynamic documentation follows the same schema. The ``http://localhost:3000/apidoc/v1.cs.html`` is documentation for version '1' of the API in the Czech language. For JSON description of the API applies the same: ``http://localhost:3000/apidoc/v1.cs.json``
+
 
 ================
 Modifying Views
@@ -940,7 +1031,7 @@ of information is already included in this tests, it just needs to be
 extracted somehow. Luckily, Apipie provides such a feature.
 
 When running the tests, set the ``APIPIE_RECORD=params`` environment
-variable. You can either use it with functional tests
+variable or call ``Apipie.record('params')`` from specs starter. You can either use it with functional tests
 
 .. code::
 
@@ -962,7 +1053,7 @@ Examples Recording
 
 You can also use the tests to generate up-to-date examples for your
 code. Similarly to the bootstrapping, you can use it with functional
-tests or a running server, setting ``APIPIE_RECORD=examples``
+tests or a running server, setting ``APIPIE_RECORD=examples`` or by calling ``Apipie.record('examples')`` in your specs starter.
 
 .. code::
 

data/app/controllers/apipie/apipies_controller.rb

@@ -24,8 +24,11 @@ module Apipie
           return
         end
 
+        @language = get_language
+
         Apipie.reload_documentation if Apipie.configuration.reload_controllers?
-        @doc = Apipie.to_json(params[:version], params[:resource], params[:method])
+        I18n.locale = @language
+        @doc = Apipie.to_json(params[:version], params[:resource], params[:method], @language)
 
         format.json do
           if @doc
@@ -43,12 +46,13 @@ module Apipie
 
           @versions = Apipie.available_versions
           @doc = @doc[:docs]
-          @doc[:link_extension] = Apipie.configuration.link_extension
+          @doc[:link_extension] = (@language ? ".#{@language}" : '')+Apipie.configuration.link_extension
           if @doc[:resources].blank?
             render "getting_started" and return
           end
           @resource = @doc[:resources].first if params[:resource].present?
           @method = @resource[:methods].first if params[:method].present?
+          @languages = Apipie.configuration.languages
 
           if @resource && @method
             render 'method'
@@ -68,20 +72,34 @@ module Apipie
 
     private
 
+    def get_language
+      lang = nil
+      [:resource, :method, :version].each do |par|
+        if params[par]
+          splitted = params[par].split('.')
+          if splitted.length > 1 && Apipie.configuration.languages.include?(splitted.last)
+            lang = splitted.last
+            params[par].sub!(".#{lang}", '')
+          end
+        end
+      end
+      lang
+    end
+
     def get_format
-      params[:format] = :html unless params[:version].sub!('.html', '').nil?
-      params[:format] = :json unless params[:version].sub!('.json', '').nil?
+      [:resource, :method, :version].each do |par|
+        if params[par]
+          params[:format] = :html unless params[par].sub!('.html', '').nil?
+          params[:format] = :json unless params[par].sub!('.json', '').nil?
+        end
+      end
       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 =~ /\.\./
+      # some params can contain dot, but only one in row
+      if [:resource, :method, :format, :version].any? { |p| params[p].to_s.gsub(".", "") =~ /\W/ || params[p].to_s =~ /\.\./ }
         head :bad_request and return
       end
 

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

@@ -7,5 +7,7 @@
         (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
     })();
 </script>
-<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
-<a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
+<noscript><%= t('apipie.enable_javascript_html', :comments_href => link_to(
+        t('apipie.comments_powered_by_disqus', :disqus => 'Disqus'),
+        "http://disqus.com/?ref_noscript")) %></noscript>
+<a href="http://disqus.com" class="dsq-brlink"><%= t('apipie.comments_powered_by_disqus', :disqus => "<span class="logo-disqus">Disqus</span>") %></a>

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

@@ -0,0 +1,6 @@
+<% if @languages && @languages.size > 1 %>
+<li class='pull-right'>
+  &nbsp;[ <%= @languages.collect { |lang| link = link_to(lang, "#{doc_url}.#{lang}.html");
+    lang==@language ? content_tag(:b, link) : link }.join(' | ').html_safe %> ]
+</li>
+<% end %>

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

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

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

@@ -9,8 +9,8 @@
     <td>
       <strong><%= param[:full_name] %> </strong><br>
       <small>
-        <%= param[:required] ? 'required' : 'optional' %>
-        <%= param[:allow_nil] ? ', nil allowed' : '' %>
+        <%= param[:required] ? t('apipie.required') : t('apipie.optional') %>
+        <%= param[:allow_nil] ? ', '+t('apipie.nil_allowed') : '' %>
       </small>
     </td>
     <td>

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

@@ -7,8 +7,8 @@
     <li>
       <strong><%= param[:name] %> </strong>:
       <small>
-        <%= param[:required] ? 'required' : 'optional' %>
-        <%= param[:allow_nil] ? ', nil allowed' : '' %>
+        <%= param[:required] ? t('apipie.required') : t('apipie.optional') %>
+        <%= param[:allow_nil] ? ', '+t('apipie.nil_allowed') : '' %>
         <% if param[:validator] %>
           [ <%= param[:validator] %> ]
         <% end %>

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

@@ -1,14 +1,17 @@
 <h1 class='page-header'>
-  Oops!
+  <%= t('apipie.oops') %>
   <small>
   <% if @resource == 'null' %>
-    Resource <code><%= params[:resource] %></code> not found.
+    <%= t('apipie.resource_not_found_html', :resource => "<code>#{params[:resource]}</code>") %>
   <% else %>
-    Method <code><%= params[:method] %></code> not found for resource <code><%= params[:resource] %></code>.
+    <%= t('apipie.method_not_found_html', :resource => "<code>#{params[:resource]}</code>",
+        :method => "<code>#{params[:resource]}</code>" %>
   <% end %>
   </small>
 </h1>
 
 <% if @doc %>
-  Try going to <a href='<%= @doc[:doc_url] %><%= @doc[:link_extension] %>'><%= @doc[:name] %> API documentation homepage</a>
+  <%= t('apipie.goto_homepage_html', :href = link_to(
+    t('apipie.goto_homepage_href', :app_name => @doc[:name]),
+    File.join(@doc[:doc_url], @doc[:link_extension]))) %>
 <% end %>

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

@@ -1,4 +1,6 @@
-<h1 class='page-header'>No documentation found</h1>
-<p>We have not found any documentation for your API.</p>
-<p>Follow <a href="https://github.com/Pajk/apipie-rails#getting-started" target="_blank">further instructions</a> on how to describe your controllers.</p>
+<h1 class='page-header'><%= t('apipie.no_doc_found') %></h1>
+<p><%= t('apipie.no_docs_found_descr') %></p>
+<p><%= t('apipie.follow_instructions_html',
+    :href => link_to(t('apipie.follow_instructions_href'),
+        "https://github.com/Pajk/apipie-rails#getting-started", :target => "_blank")) %></p>
 

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

@@ -1,15 +1,16 @@
 <ul class='breadcrumb'>
   <li class='active'><a href='<%= @doc[:doc_url] %><%= @doc[:link_extension] %>'><%= @doc[:name] %> <%= @doc[:resources].values.first[:version] %></a></li>
+  <%= render(:partial => "languages", :locals => {:doc_url => @doc[:doc_url]}) %>
   <% if @versions && @versions.size > 1 %>
   <li class='pull-right'>
-    <%= @versions.collect { |v| link_to v, Apipie.full_url(v) }.join(' / ').html_safe %>
+    <%= @versions.collect { |v| link_to v, Apipie.full_url(v+@doc[:link_extension]) }.join(' / ').html_safe %>
   </li>
   <% end %>
 </ul>
 
 <div><%= raw @doc[:info] %></div>
 
-<h1 class='page-header'>Resources</h1>
+<h1 class='page-header'><%= t('apipie.resources') %></h1>
 
 <% @doc[:resources].sort_by(&:first).each do |key, api| %>
   <h2>
@@ -21,8 +22,8 @@
   <table class='table'>
     <thead>
       <tr>
-        <th>Resource</th>
-        <th>Description</th>
+        <th><%= t('apipie.resource') %></th>
+        <th><%= t('apipie.description') %></th>
       </tr>
     </thead>
     <tbody>
@@ -38,6 +39,6 @@
   </table>
 <% 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/apipie/apipies/method.html.erb

@@ -11,6 +11,8 @@
     <span class='divider'>/</span>
   </li>
   <li class='active'><%= @method[:name] %></li>
+  <%= render(:partial => "languages", :locals => {:doc_url => @method[:doc_url]}) %>
+
 </ul>
 
 <% @method[:apis].each do |api| %>
@@ -30,6 +32,6 @@
   <%= render(:partial => "method_detail", :locals => {:method => @method, :h_level => 2}) %>
 </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/plain.html.erb

@@ -45,14 +45,14 @@
       <div>
         <%= raw method[:full_description] %>
         <% unless method[:examples].blank? %>
-          <h4>Examples</h4>
+          <h4><%= t('apipie.examples') %></h4>
           <% method[:examples].each do |example| %>
             <pre class="wiki"><%= example %></pre>
           <% end %>
         <% end %>
 
         <% unless method[:errors].blank? %>
-          <h4>Errors</h4>
+          <h4><%= t('apipie.errors') %></h4>
           <% method[:errors].each do |err| %>
             <%= err[:code] %>
             <%= err[:description] %>
@@ -62,7 +62,7 @@
         <% end %>
 
         <% unless method[:params].blank? %>
-          <h4>Params</h4>
+          <h4><%= t('apipie.params') %></h4>
           <%= render(:partial => "params_plain", :locals => {:params => method[:params]}) %>
         <% end %>
       </div>