Allow for resource-level deprecations

Resources can now be marked as deprecated. This marking is also
referenced at the method level, meaning that resources marked as
deprecated will have all their methods marked as such as well.
This commit also includes related updates to the views used for
generating documentation

README.rst

@@ -136,6 +136,9 @@ app_info
 meta
   Hash or array with custom metadata.
 
+deprecated
+  Boolean value indicating if the resource is marked as deprecated. (Default false)
+
 Example:
 ~~~~~~~~
 
@@ -154,6 +157,7 @@ Example:
      error 500, "Server crashed for some <%= reason %>", :meta => {:anything => "you can think of"}
      error :unprocessable_entity, "Could not save the entity."
      meta :author => {:name => 'John', :surname => 'Doe'}
+     deprecated false
      description <<-EOS
        == Long description
         Example resource for rest api documentation

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

@@ -16,7 +16,11 @@
   <h2>
     <a href='<%= api[:doc_url] %><%= @doc[:link_extension] %>'>
       <%= api[:name] %>
-    </a><br>
+    </a>
+    <% if api[:deprecated] %>
+        <code>DEPRECATED</code>
+    <% end %>
+    <br>
     <small><%= api[:short_description] %></small>
   </h2>
   <table class='table'>

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

@@ -13,6 +13,9 @@
 <div class='page-header'>
   <h1>
     <%= @resource[:name] %>
+    <% if api[:deprecated] %>
+        <code>DEPRECATED</code>
+    <% end %>
     <br>
     <small><%= raw @resource[:short_description] %></small>
   </h1>

lib/apipie/dsl_definition.rb

@@ -42,7 +42,8 @@ def _apipie_dsl_data_init
          :formats           => nil,
          :api_versions      => [],
          :meta              => nil,
-         :show              => true
+         :show              => true,
+         :deprecated        => false
        }
       end
     end
@@ -76,6 +77,11 @@ def path(path)
       def app_info(app_info)
         _apipie_dsl_data[:app_info] = app_info
       end
+
+      def deprecated(value)
+        _apipie_dsl_data[:deprecated] = value
+      end
+
     end
 
     module Action

lib/apipie/method_description.rb

@@ -129,7 +129,7 @@ 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),
-          :deprecated => api.options[:deprecated]
+          :deprecated => resource._deprecated || api.options[:deprecated]
         }
       end
     end

lib/apipie/resource_description.rb

@@ -10,11 +10,12 @@ module Apipie
   # id - resouce name
   # formats - acceptable request/response format types
   # headers - array of headers
+  # deprecated - boolean indicating if resource is deprecated
   class ResourceDescription
 
     attr_reader :controller, :_short_description, :_full_description, :_methods, :_id,
       :_path, :_name, :_params_args, :_errors_args, :_formats, :_parent, :_metadata,
-      :_headers
+      :_headers, :_deprecated
 
     def initialize(controller, resource_name, dsl_data = nil, version = nil, &block)
 
@@ -42,6 +43,7 @@ def update_from_dsl_data(dsl_data)
       @_metadata = dsl_data[:meta]
       @_api_base_url = dsl_data[:api_base_url]
       @_headers = dsl_data[:headers]
+      @_deprecated = dsl_data[:deprecated] || false
 
       if dsl_data[:app_info]
         Apipie.configuration.app_info[_version] = dsl_data[:app_info]
@@ -109,7 +111,8 @@ def to_json(method_name = nil, lang = nil)
         :formats => @_formats,
         :metadata => @_metadata,
         :methods => methods,
-        :headers => _headers
+        :headers => _headers,
+        :deprecated => @_deprecated
       }
     end
 

spec/lib/method_description_spec.rb

@@ -36,6 +36,13 @@
       method = Apipie::MethodDescription.new(:a, @resource, dsl_data)
       expect(method.method_apis_to_json.first[:deprecated]).to eq(true)
     end
+
+    it "should return the deprecated flag if resource is deprecated" do
+      @resource.instance_variable_set("@_deprecated", true)
+      dsl_data[:api_args] = [[:GET, "/foo/bar", "description", {}]]
+      method = Apipie::MethodDescription.new(:a, @resource, dsl_data)
+      expect(method.method_apis_to_json.first[:deprecated]).to eq(true)
+    end
   end
 
   describe "params descriptions" do