Merge pull request #268 from komidore64/deprecated-route-flag

adding an option to flag an api route as deprecated

README.rst

@@ -860,17 +860,21 @@ the resource belong to `config.default_version` ("1.0" by default)
      api_versions "1", "2"
    end
 
-   api :GET, "/api/users/"
+   api :GET, "/api/users/", "List: users"
    api_version "1"
    def index
      # ...
    end
 
+   api :GET, "/api/users/", "List: users", :deprecated => true
+
 In the example above we say the whole controller/resource is defined
 for versions "1" and "2", but we override this with explicitly saying
 `index` belongs only to version "1". Also inheritance works (therefore
 we can specify the api_version for the parent controller and all
-children will know about that).
+children will know about that). Routes can be flagged as deprecated
+and an annotation will be added to them when viewing in the API
+documentation.
 
 From the Apipie API perspective, the resources belong to version.
 With versioning, there are paths like this provided by apipie:

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

@@ -30,7 +30,12 @@
       <% api[:methods].each do |m| %>
         <% m[:apis].each do |a| %>
           <tr>
-            <td><a href='<%= m[:doc_url] %><%= @doc[:link_extension] %>'><%= a[:http_method] %> <%= a[:api_url] %></a></td>
+            <td>
+              <a href='<%= m[:doc_url] %><%= @doc[:link_extension] %>'><%= a[:http_method] %> <%= a[:api_url] %></a>
+              <% if a[:deprecated] %>
+                <code>DEPRECATED</code>
+              <% end %>
+            </td>
             <td width='60%'><%= a[:short_description] %></td>
           </tr>
         <% end %>

app/views/apipie/apipies/method.html.erb

@@ -18,7 +18,11 @@
 <% @method[:apis].each do |api| %>
   <div class='page-header'>
     <h1>
-      <%= api[:http_method] %> <%= api[:api_url] %><br>
+      <%= api[:http_method] %> <%= api[:api_url] %>
+      <% if api[:deprecated] %>
+        <code>DEPRECATED</code>
+      <% end %>
+      <br>
       <small><%= raw api[:short_description] %></small>
     </h1>
   </div>

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

@@ -47,7 +47,11 @@
            data-toggle='collapse'
            data-parent='#accordion'>
             <%= api[:http_method] %> <%= api[:api_url] %>
-          </a><br>
+          </a>
+          <% if api[:deprecated] %>
+            <code>DEPRECATED</code>
+          <% end %>
+          <br>
           <small><%= raw api[:short_description] %></small>
         </h2>
       <% end %>

lib/apipie/dsl_definition.rb

@@ -79,7 +79,7 @@ def def_param_group(name, &block)
       #
       def api(method, path, desc = nil, options={}) #:doc:
         return unless Apipie.active_dsl?
-        _apipie_dsl_data[:api_args] << [method, path, desc]
+        _apipie_dsl_data[:api_args] << [method, path, desc, options]
       end
 
       # Reference other similar method

lib/apipie/method_description.rb

@@ -5,12 +5,13 @@ class MethodDescription
 
     class Api
 
-      attr_accessor :short_description, :path, :http_method
+      attr_accessor :short_description, :path, :http_method, :options
 
-      def initialize(method, path, desc)
+      def initialize(method, path, desc, options)
         @http_method = method.to_s
         @path = path
         @short_description = desc
+        @options = options
       end
 
     end
@@ -22,8 +23,8 @@ def initialize(method, resource, dsl_data)
       @resource = resource
       @from_concern = dsl_data[:from_concern]
 
-      @apis = dsl_data[:api_args].map do |method, path, desc|
-        MethodDescription::Api.new(method, concern_subst(path), concern_subst(desc))
+      @apis = dsl_data[:api_args].map do |mthd, path, desc, opts|
+        MethodDescription::Api.new(mthd, concern_subst(path), concern_subst(desc), opts)
       end
 
       desc = dsl_data[:description] || ''
@@ -113,7 +114,8 @@ def method_apis_to_json(lang = nil)
         {
           :api_url => create_api_url(api),
           :http_method => api.http_method.to_s,
-          :short_description => Apipie.app.translate(api.short_description, lang)
+          :short_description => Apipie.app.translate(api.short_description, lang),
+          :deprecated => api.options[:deprecated]
         }
       end
     end

spec/lib/method_description_spec.rb

@@ -26,6 +26,18 @@
 
   end
 
+  describe "deprecated flag" do
+    before(:each) do
+      @resource = Apipie::ResourceDescription.new(ApplicationController, "dummy")
+    end
+
+    it "should return the deprecated flag when provided" do
+      dsl_data[:api_args] = [[:GET, "/foo/bar", "description", :deprecated => true]]
+      method = Apipie::MethodDescription.new(:a, @resource, dsl_data)
+      method.method_apis_to_json.first[:deprecated].should == true
+    end
+  end
+
   describe "params descriptions" do
 
     before(:each) do