apipie-rails 0.3.4 → 0.3.5

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MTljNTJlOWI1NzIzODJhNDg5MjlhODc4ZmY4OTc4MzY2MzRiNmYzMA==
+  data.tar.gz: !binary |-
+    Nzk2MjA1OGE1MDliZjk3M2IzMTkzZTYzODc3YTY3YWQ0ZDY3OWNmYw==
+SHA512:
+  metadata.gz: !binary |-
+    OGFlOWZmOWY3ZjUyZGRkMmZkZGRkYWExMDY3MDJmYTA0NDIyODRlOTZlOTk4
+    ZDQ1NjAxOWU4NWVlOTBjOWZmMjUxNDY0OTg2YWNlMGQ1NTdjMTA0NDFjZTk3
+    NDc1ODQ4MGU4YTFkNjg5YWE2ZmM2N2NjOTY2YzgzMTgwYjA3NzU=
+  data.tar.gz: !binary |-
+    Y2ZhMjhlMDY4N2Q1NTE3NmZiOGE0M2FlOGM0ODMxMWQ5NGI3NjRlYTVlM2E5
+    YzU0ZmIyOWI4OWM5NzFhOWJiZWJlYTVmZjliOGYzODY0YmE0MjdhZGE1NTJh
+    MDFlMTFjMTNiMDRiMmI5NDkzOWQ0YTI1ZGYxNmNjYjhjZDU3ZTc=

data/CHANGELOG.md

@@ -2,6 +2,26 @@
  Changelog
 ===========
 
+v0.3.5
+------
+
+* Cleaning up unreachable code
+  [#385](https://github.com/Apipie/apipie-rails/pull/385) [@voxik][]
+* Russian translation
+  [#352](https://github.com/Apipie/apipie-rails/pull/352) [@Le6ow5k1][]
+* Ability to hide controller methods from documentation
+  [#356](https://github.com/Apipie/apipie-rails/pull/356) [@davidcollie][]
+* Use doc_path configuration in rake tasks
+  [#358](https://github.com/Apipie/apipie-rails/pull/358)  [@saneshark][]
+* Chinese translation
+  [#363](https://github.com/Apipie/apipie-rails/pull/363)  [@debbbbie][]
+* Polish translation
+  [#375](https://github.com/Apipie/apipie-rails/pull/375)  [@dbackowski][]
+* Spanish translation
+  [#376](https://github.com/Apipie/apipie-rails/pull/376)  [@isseu][]
+* Add an alternative to action aware required param
+  [#377](https://github.com/Apipie/apipie-rails/pull/377)  [@mourad-ifeelgoods][]
+
 v0.3.4
 ------
 
@@ -291,3 +311,10 @@ v0.0.15
 [@iliabylich]: https://github.com/iliabylich
 [@dadario]: https://github.com/dadario
 [@saneshark]: https://github.com/saneshark
+[@voxik]: https://github.com/voxik
+[@Le6ow5k1]: https://github.com/Le6ow5k1
+[@davidcollie]: https://github.com/davidcollie
+[@saneshark]: https://github.com/saneshark
+[@debbbbie]: https://github.com/debbbbie
+[@dbackowski]: https://github.com/dbackowski
+[@isseu]: https://github.com/isseu

data/README.rst

@@ -27,11 +27,11 @@ Getting started
 
 The easiest way to get Apipie up and running with your app is:
 
-.. code::
+.. code:: sh
 
-   $ echo "gem 'apipie-rails'" >> Gemfile
-   $ bundle install
-   $ rails g apipie:install
+   echo "gem 'apipie-rails'" >> Gemfile
+   bundle install
+   rails g apipie:install
 
 Now you can start documenting your resources and actions (see
 `DSL Reference`_ for more info):
@@ -56,8 +56,8 @@ features such as generating documentation from tests, recording examples etc.
 Screenshots
 -----------
 
-.. image:: https://img.skitch.com/20120428-nruk3e87xs2cu4ydsjujdh11fq.png
-.. image:: https://img.skitch.com/20120428-bni2cmq5cyhjuw1jkd78e3qjxn.png
+.. image:: https://github.com/Apipie/apipie-rails/blob/master/images/screenshot-1.png
+.. image:: https://github.com/Apipie/apipie-rails/blob/master/images/screenshot-2.png
 
 Authors
 -------
@@ -224,6 +224,9 @@ see
 meta
   Hash or array with custom metadata.
 
+show
+  Resource is hidden from documentation when set to false (true by default)
+
 Example:
 ~~~~~~~~
 
@@ -236,6 +239,7 @@ Example:
 
    # More complex example
    api :GET, "/users/:id", "Show user profile"
+   show false
    error :code => 401, :desc => "Unauthorized"
    error :code => 404, :desc => "Not Found", :meta => {:anything => "you can think of"}
    param :session, String, :desc => "user is logged in", :required => true
@@ -857,8 +861,8 @@ Adding custom validator
 Only basic validators are included but it is really easy to add your own.
 Create a new initializer with a subclass of Apipie::Validator::BaseValidator.
 Two methods are required to implement this - instance method
-<tt>validate(value)</tt> and class method
-<tt>build(param_description, argument, options, block)</tt>.
+:code:`validate(value)` and class method
+:code:`build(param_description, argument, options, block)`.
 
 When searching for the validator +build+ method, every subclass of
 Apipie::Validator::BaseValidator is called. The first one that returns the
@@ -1095,6 +1099,9 @@ When you want to avoid any unnecessary computation in production mode,
 you can generate a cache with ``rake apipie:cache`` and configure the
 app to use it in production with ``config.use_cache = Rails.env.production?``
 
+Default cache dir is ``File.join(Rails.root, "public", "apipie-cache")``, 
+you can change it to where you want, example: ``config.cache_dir = File.join(Rails.root, "doc", "apidoc")``.
+
 If, for some complex cases, you need to generate/re-generate just part of the cache
 use ``rake apipie:cache cache_part=index`` resp. ``rake apipie:cache cache_part=resources``
 To generate it for different locations for further processing use ``rake apipie:cache OUT=/tmp/apipie_cache``.
@@ -1263,8 +1270,8 @@ further versions.
 
 There is, however, an even better and more flexible way to reuse your API
 documentation for this purpose: using the API the Apipie
-provides in the generator code. Check out
-`Foreman API bindings <https://github.com/mbacovsky/foreman_api>`_, as they
+provides in the generator code. Check out our sister project
+`apipie-bindings <https://github.com/Apipie/apipie-bindings>`_, as they
 use exactly this approach. You also don't need to run the service,
 provided it uses Apipie as a backend.
 
@@ -1294,4 +1301,4 @@ configuration:
 
 * `Read-world application usage with versioning <https://github.com/theforeman/foreman>`_
 
-* `Using Apipie API to generate bindings <https://github.com/mbacovsky/foreman_api>`_
+* `Using Apipie API to generate bindings <https://github.com/Apipie/apipie-bindings>`_

data/app/helpers/apipie_helper.rb

@@ -1,4 +1,5 @@
 module ApipieHelper
+  include ActionView::Helpers::TagHelper
 
   def heading(title, level=1)
     content_tag("h#{level}") do

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

@@ -28,6 +28,9 @@
     </thead>
     <tbody>
       <% api[:methods].each do |m| %>
+        <% if !m[:show] %>
+          <% next %>
+        <% end %>
         <% m[:apis].each do |a| %>
           <tr>
             <td>

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

@@ -2,6 +2,9 @@
   <h4><a href='#<%= key %>'><%= resource[:name] %></a></h4>
   <ul>
     <% resource[:methods].each do |method| %>
+      <% if !method[:show] %>
+        <% next %>
+      <% end %>
       <li><a href='#<%= key %>-<%= method[:name] %>'><%= method[:name] %></a></li>
     <% end %>
   </ul>
@@ -26,6 +29,9 @@
   <div>
 
     <% resource[:methods].each do |method| %>
+      <% if !method[:show] %>
+        <% next %>
+      <% end %>
       <hr/>
 
       <h3 id="<%= "#{key}-#{method[:name]}" %>">

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

@@ -37,6 +37,9 @@
 <div class='accordion' id='accordion'>
 
   <% @resource[:methods].each do |m| %>
+    <% if !m[:show] %>
+      <% next %>
+    <% end %>
     <hr>
     <div class='pull-right small'>
       <a href='<%= m[:doc_url] %><%= @doc[:link_extension] %>'> >>> </a>

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

@@ -2,6 +2,9 @@
   <h4><a href='#<%= key %>'><%= resource[:name] %></a></h4>
   <ul>
     <% resource[:methods].each do |method| %>
+      <% if !method[:show] %>
+        <% next %>
+      <% end %>
       <li><a href='#<%= key %>-<%= method[:name] %>'><%= method[:name] %></a></li>
     <% end %>
   </ul>
@@ -34,6 +37,9 @@
   <div class='accordion' id='accordion'>
 
     <% resource[:methods].each do |method| %>
+      <% if !method[:show] %>
+        <% next %>
+      <% end %>
       <hr>
 
       <ul class='breadcrumb' id='<%= key %>-<%= method[:name] %>'>

data/config/locales/es.yml

@@ -0,0 +1,28 @@
+es:
+    apipie:
+        resources: Recursos
+        resource: Recurso
+        description: Descripción
+        no_docs_found: No se encontró la documentación
+        no_docs_found_descr: No hemos encontrado ninguna documentación para tu API.
+        follow_instructions_html: Siga %{href} sobre cómo describir sus controladores.
+        follow_instructions_href: más instrucciones
+        oops: Huy!!
+        resource_not_found_html: Recurso %{res} no encontrado.
+        method_not_found_html: Método  %{method} no encontrado para el recurso %{resource}.
+        goto_homepage_html: Trate de ir a %{href}
+        goto_homepage_href: "%{app_name} página de documentación API  "
+        required: requerido
+        optional: opcional
+        nil_allowed: nil permitido
+        param_name: Nombre del parámetro
+        params: Parámetros
+        examples: Ejemplos
+        metadata: Metadatos
+        errors: Errores
+        supported_formats: Formatos soportados
+        enable_javascript_html: Por favor, active JavaScript para ver el %{comments_href}.
+        comments_powered_by_disqus: comentarios gracias a %{disqus}
+        api_documentation: Documentación de la API
+        headers: Cabeceras
+        header_name: Nombre de cabecera

data/config/locales/pl.yml

@@ -0,0 +1,29 @@
+pl:
+    apipie:
+        resources: Zasoby
+        resource: Zasób 
+        description: Opis
+        no_docs_found: Nie znalezionio dokumentacji
+        no_docs_found_descr: Nie znaleziono dokumentacji dla twojego API.
+        follow_instructions_html: Przejdź do %{href} aby opisać swoje kontrolery.
+        follow_instructions_href: dalsze instrukcje
+        oops: Ups!!
+        resource_not_found_html: Zasób %{res} nie został znaleziony.
+        method_not_found_html: Metoda %{method} dla zasobu %{resource} nie została znaleziona.
+        goto_homepage_html: Spróbuj przejść do %{href}
+        goto_homepage_href: "%{app_name} Strona główna dokumentacji API"
+        required: wymagany 
+        optional: opcjonalny
+        nil_allowed: nil dopuszczalny
+        param_name: Nazwa parametru
+        params: Parametry
+        examples: Przykłady
+        metadata: Metadane
+        errors: Błędy
+        supported_formats: Dostępne formaty
+        enable_javascript_html: Proszę włączyć obsługę javascript w celu zobaczenia %{comments_href}.
+        comments_powered_by_disqus: komentarze obsługiwane przez %{disqus}
+        api_documentation: Dokumentacja API
+        headers: Nagłówki
+        header_name: Nazwa nagłówka
+

data/config/locales/ru.yml

@@ -0,0 +1,29 @@
+ru:
+    apipie:
+        resources: Ресурсы
+        resource: Ресурс
+        description: Описание
+        no_docs_found: Документация не найдена
+        no_docs_found_descr: Мы не нашли никакой документации для вашего API.
+        follow_instructions_html: Перейдите по ссылке %{href}, чтобы узнать как описать ваш API.
+        follow_instructions_href: дополнительные инструкции
+        oops: Ой!!
+        resource_not_found_html: Ресурс %{res} не найден.
+        method_not_found_html: Метод %{method} для ресурса %{resource} не найден.
+        goto_homepage_html: Перейдите %{href}
+        goto_homepage_href: "%{app_name} домашняя страница API документации"
+        required: обязательно
+        optional: необязательно
+        nil_allowed: nil разрешен
+        param_name: Имя параметра
+        params: Параметры
+        examples: Примеры
+        metadata: Метаданные
+        errors: Ошибки
+        supported_formats: Поддерживаемые форматы
+        enable_javascript_html: Пожалуйста включите JavaScript, чтобы просматривать %{comments_href}.
+        comments_powered_by_disqus: комментарии представлены %{disqus}
+        api_documentation: API документация
+        headers: Заголовки
+        header_name: Название заголовка
+

data/config/locales/zh-CN.yml

@@ -0,0 +1,28 @@
+'zh-CN':
+  apipie:
+    resources: 资源
+    resource: 资源
+    description: 描述
+    no_docs_found: 没有找到文档
+    no_docs_found_descr: 没有找到文档。
+    follow_instructions_html: 点击 %{href} 查看描述。
+    follow_instructions_href: 高级指导
+    oops: Oops!!
+    resource_not_found_html: 没有找到资源 %{res} 。
+    method_not_found_html: 没有找到资源 %{res} 的方法 %{method} 。
+    goto_homepage_html: 试图访问 %{href}
+    goto_homepage_href: "%{app_name} API 文档主页"
+    required: 必填
+    optional: 选填
+    nil_allowed: 允许空值
+    param_name: 参数名字
+    params: 参数
+    examples: 示例
+    metadata: 元数据
+    errors: 错误
+    supported_formats: 支持格式
+    enable_javascript_html: 浏览 %{comments_href}前请允许执行 JavaScript 。
+    comments_powered_by_disqus: 评论技术支持 %{disqus}
+    api_documentation: API 文档
+    headers: 头部
+    header_name: 头部名字

data/config/locales/zh-TW.yml

@@ -0,0 +1,28 @@
+'zh-TW':
+  apipie:
+    resources: 資源
+    resource: 資源
+    description: 描述
+    no_docs_found: 沒有找到文檔
+    no_docs_found_descr: 沒有找到文檔。
+    follow_instructions_html: 點擊 %{href} 查看描述。
+    follow_instructions_href: 高級指導
+    oops: Oops!!
+    resource_not_found_html: 沒有找到資源 %{res} 。
+    method_not_found_html: 沒有找到資源 %{res} 的方法 %{method} 。
+    goto_homepage_html: 試圖訪問 %{href}
+    goto_homepage_href: "%{app_name} API 文檔主頁"
+    required: 必填
+    optional: 選填
+    nil_allowed: 允許空值
+    param_name: 參數名字
+    params: 參數
+    examples: 示例
+    metadata: 元數據
+    errors: 錯誤
+    supported_formats: 支持格式
+    enable_javascript_html: 瀏覽 %{comments_href}前請允許執行 JavaScript 。
+    comments_powered_by_disqus: 評論技術支持 %{disqus}
+    api_documentation: API 文檔
+    headers: 頭部
+    header_name: 頭部名字

data/lib/apipie/dsl_definition.rb

@@ -33,7 +33,8 @@ module Apipie
          :see               => [],
          :formats           => nil,
          :api_versions      => [],
-         :meta              => nil
+         :meta              => nil,
+         :show              => true
        }
       end
     end
@@ -111,6 +112,13 @@ module Apipie
         _apipie_dsl_data[:examples] << example.strip_heredoc
       end
 
+      # Determine if the method should be included
+      # in the documentation
+      def show(show)
+        return unless Apipie.active_dsl?
+        _apipie_dsl_data[:show] = show
+      end
+
       # Describe whole resource
       #
       # Example:

data/lib/apipie/extractor/writer.rb

@@ -53,7 +53,7 @@ module Apipie
       end
 
       def self.examples_file
-        File.join(Rails.root,"doc","apipie_examples.json")
+        File.join(Rails.root,Apipie.configuration.doc_path,"apipie_examples.json")
       end
 
       protected

data/lib/apipie/method_description.rb

@@ -17,7 +17,7 @@ module Apipie
 
     end
 
-    attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats, :metadata, :headers
+    attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats, :metadata, :headers, :show
 
     def initialize(method, resource, dsl_data)
       @method = method.to_s
@@ -49,6 +49,12 @@ module Apipie
       end
       @params_ordered = ParamDescription.unify(@params_ordered)
       @headers = dsl_data[:headers]
+
+      @show = if dsl_data.has_key? :show
+        dsl_data[:show]
+      else
+        true
+      end
     end
 
     def id
@@ -144,7 +150,8 @@ module Apipie
         :examples => @examples,
         :metadata => @metadata,
         :see => see.map(&:to_json),
-        :headers => headers
+        :headers => headers,
+        :show => @show
       }
     end
 

data/lib/apipie/param_description.rb

@@ -47,11 +47,7 @@ module Apipie
       @parent = @options[:parent]
       @metadata = @options[:meta]
 
-      @required = if @options.has_key? :required
-        @options[:required]
-      else
-        Apipie.configuration.required_by_default?
-      end
+      @required = is_required?
 
       @show = if @options.has_key? :show
         @options[:show]
@@ -210,6 +206,18 @@ module Apipie
       concern_subst(Apipie.markup_to_html(text || ''))
     end
 
+    def is_required?
+      if @options.has_key?(:required)
+        if (@options[:required] == true) || (@options[:required] == false)
+          @options[:required]
+        else
+          Array(@options[:required]).include?(@method_description.method.to_sym)
+        end
+      else
+        Apipie.configuration.required_by_default?
+      end
+    end
+
   end
 
 end