Merge pull request #356 from davidcollie/master

Hide controller methods from documentation

Author: iNecas

README.rst

@@ -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

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>

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]}" %>">

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>

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] %>'>

lib/apipie/dsl_definition.rb

@@ -33,7 +33,8 @@ def _apipie_dsl_data_init
          :see               => [],
          :formats           => nil,
          :api_versions      => [],
-         :meta              => nil
+         :meta              => nil,
+         :show              => true
        }
       end
     end
@@ -111,6 +112,13 @@ def example(example) #:doc:
         _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:

lib/apipie/method_description.rb

@@ -17,7 +17,7 @@ def initialize(method, path, desc, options)
 
     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 @@ def initialize(method, resource, dsl_data)
       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 @@ def to_json(lang=nil)
         :examples => @examples,
         :metadata => @metadata,
         :see => see.map(&:to_json),
-        :headers => headers
+        :headers => headers,
+        :show => @show
       }
     end
 

spec/controllers/users_controller_spec.rb

@@ -402,6 +402,7 @@ def reload_controllers
       context "the key is valid" do
         it "should contain reference to another method" do
           api = Apipie[UsersController, :see_another]
+          api.show.should == false
           see = api.see.first
           see.see_url.should == Apipie[UsersController, :create].doc_url
           see.link.should == 'development#users#create'
@@ -571,6 +572,7 @@ def reload_controllers
                      :expected_type=>"numeric"},
        ],
         :name => 'two_urls',
+        :show => true,
         :apis => [
           {
             :http_method => 'GET',

spec/dummy/app/controllers/users_controller.rb

@@ -169,6 +169,7 @@ class UsersController < ApplicationController
     More builder documentation can be found at http://builder.rubyforge.org.
   eos
   api :GET, "/users/:id", "Show user profile"
+  show false
   formats ['json', 'jsonp']
   error 401, "Unauthorized"
   error :code => 404, :description => "Not Found"
@@ -256,9 +257,10 @@ def two_urls
   end
 
   api :GET, '/users/see_another', 'Boring method'
+  show false
   see 'development#users#create'
   see 'development#users#index', "very interesting method reference"
-  desc 'This method is boring, look at users#create'
+  desc 'This method is boring, look at users#create.  It is hidden from documentation.'
   def see_another
     render :text => 'This is very similar to create action'
   end