From 63414d85c0a0e7608bcfaa91ccb717c822b9c202 Mon Sep 17 00:00:00 2001
From: Colin Ross <cross@parallel6.com>
Date: Thu, 2 Nov 2017 08:16:02 -0700
Subject: [PATCH] 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                                 | 4 ++++
 app/views/apipie/apipies/index.html.erb    | 6 +++++-
 app/views/apipie/apipies/resource.html.erb | 3 +++
 lib/apipie/dsl_definition.rb               | 8 +++++++-
 lib/apipie/method_description.rb           | 2 +-
 lib/apipie/resource_description.rb         | 7 +++++--
 spec/lib/method_description_spec.rb        | 7 +++++++
 7 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/README.rst b/README.rst
index aad752cc..ea838d36 100644
--- a/README.rst
+++ b/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
diff --git a/app/views/apipie/apipies/index.html.erb b/app/views/apipie/apipies/index.html.erb
index 5f29bf2c..76a4fa2d 100644
--- a/app/views/apipie/apipies/index.html.erb
+++ b/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'>
diff --git a/app/views/apipie/apipies/resource.html.erb b/app/views/apipie/apipies/resource.html.erb
index 11fbff72..ffd91274 100644
--- a/app/views/apipie/apipies/resource.html.erb
+++ b/app/views/apipie/apipies/resource.html.erb
@@ -13,6 +13,9 @@
 <div class='page-header'>
   <h1>
     <%= @resource[:name] %>
+    <% if @resource[:deprecated] %>
+        <code>DEPRECATED</code>
+    <% end %>
     <br>
     <small><%= raw @resource[:short_description] %></small>
   </h1>
diff --git a/lib/apipie/dsl_definition.rb b/lib/apipie/dsl_definition.rb
index 1a566974..c16cbee8 100644
--- a/lib/apipie/dsl_definition.rb
+++ b/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
diff --git a/lib/apipie/method_description.rb b/lib/apipie/method_description.rb
index 850e6e7e..0f07380c 100644
--- a/lib/apipie/method_description.rb
+++ b/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
diff --git a/lib/apipie/resource_description.rb b/lib/apipie/resource_description.rb
index 083d6c25..9fc160df 100644
--- a/lib/apipie/resource_description.rb
+++ b/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
 
diff --git a/spec/lib/method_description_spec.rb b/spec/lib/method_description_spec.rb
index 935e1a24..04cba43c 100644
--- a/spec/lib/method_description_spec.rb
+++ b/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