Allow Apipie::ParamDescription to be marked as deprecated

.rubocop.yml

@@ -27,6 +27,7 @@ Layout/LineLength:
     - spec/dummy/config/initializers/secret_token.rb
     - spec/lib/application_spec.rb
     - spec/lib/param_description_spec.rb
+    - spec/lib/param_description_deprecation_spec.rb
     - spec/lib/swagger/response_validation_spec.rb
     - spec/spec_helper.rb
 
@@ -110,3 +111,7 @@ Style/Documentation:
     - spec/support/custom_bool_validator.rb
     - spec/lib/validators/array_validator_spec.rb
     - spec/dummy/**/*.rb
+
+RSpec/FilePath:
+  Exclude:
+    - 'spec/lib/param_description/deprecation_spec.rb'

README.rst

@@ -355,6 +355,22 @@ Example:
      #...
    end
 
+deprecated
+  Indicates if the parameter is marked as deprecated.
+
+Example
+~~~~~~~~
+
+.. code:: ruby
+
+   param :pet_name, String, desc: "Name of pet", deprecated: true
+   param :pet_name, String, desc: "Name of pet", deprecated: 'Some deprecation info'
+   param :pet_name, String, desc: "Name of pet", deprecated: { in: "2.3", info: "Something", sunset: "3.0" }
+   def create
+     #...
+   end
+
+
 DRY with param_group
 --------------------
 

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

@@ -0,0 +1,16 @@
+<% if deprecation.present? %>
+  <strong><%= t('apipie.deprecation_details') %></strong>
+  <ul>
+    <% if deprecation[:deprecated_in].present? %>
+      <li><%= t('apipie.deprecation.attributes.deprecated_in') %>: <%= deprecation[:deprecated_in] %></li>
+    <% end %>
+
+    <% if deprecation[:sunset_at].present? %>
+      <li><%= t('apipie.deprecation.attributes.sunset_at') %>: <%= deprecation[:sunset_at] %></li>
+    <% end %>
+
+    <% if deprecation[:info].present? %>
+      <li><%= t('apipie.deprecation.attributes.info') %>: <%= deprecation[:info] %></li>
+    <% end %>
+  </ul>
+<% end %>

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

@@ -7,7 +7,11 @@
   <% end %>
   <tr style='background-color:rgb(<%= "#{col},#{col},#{col}" %>);'>
     <td>
-      <strong><%= param[:full_name] %> </strong><br>
+      <strong><%= param[:full_name] %></strong>
+      <% if param[:deprecated].present? %>
+        <code><%= t('apipie.deprecated').upcase %></code>
+      <% end %>
+      <br>
       <small>
         <%= param[:required] ? t('apipie.required') : t('apipie.optional') %>
         <%= param[:allow_nil] ? ', '+t('apipie.nil_allowed') : '' %>
@@ -29,6 +33,8 @@
         </ul>
       <%- end %>
 
+      <%= render partial: 'deprecation', locals: { deprecation: param[:deprecation] } %>
+
       <% unless param[:metadata].blank? %>
         <br>
         Metadata:

config/locales/en.yml

@@ -30,3 +30,10 @@ en:
     headers: Headers
     header_name: Header name
     code: Code
+    deprecated: Deprecated
+    deprecation_details: Deprecation details
+    deprecation:
+      attributes:
+        deprecated_in: Deprecated in
+        sunset_at: Sunset at
+        info: Info

lib/apipie-rails.rb

@@ -12,6 +12,7 @@
 require "apipie/method_description"
 require "apipie/resource_description"
 require "apipie/param_description"
+require "apipie/param_description/deprecation"
 require "apipie/method_description/api"
 require "apipie/method_description/apis_service"
 require "apipie/errors"

lib/apipie/param_description.rb

@@ -97,6 +97,7 @@ def initialize(method_description, name, validator, desc_or_options = nil, optio
       @validations = Array(options[:validations]).map {|v| concern_subst(Apipie.markup_to_html(v)) }
 
       @additional_properties = @options[:additional_properties]
+      @deprecated = @options[:deprecated] || false
     end
 
     def from_concern?
@@ -166,8 +167,14 @@ def to_json(lang = nil)
         expected_type: validator.expected_type,
         metadata: metadata,
         show: show,
-        validations: validations
+        validations: validations,
+        deprecated: deprecated?
       }
+
+      if deprecation.present?
+        hash[:deprecation] = deprecation.to_json
+      end
+
       if sub_params = validator.params_ordered
         hash[:params] = sub_params.map { |p| p.to_json(lang)}
       end
@@ -281,6 +288,24 @@ def is_required?
       end
     end
 
+    def deprecated?
+      @deprecated.present?
+    end
+
+    def deprecation
+      return if @deprecated.blank? || @deprecated == true
+
+      case @deprecated
+      when Hash
+        Apipie::ParamDescription::Deprecation.new(
+          info: @deprecated[:info],
+          deprecated_in: @deprecated[:in],
+          sunset_at: @deprecated[:sunset]
+        )
+      when String
+        Apipie::ParamDescription::Deprecation.new(info: @deprecated)
+      end
+    end
   end
 
 end

lib/apipie/param_description/deprecation.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Apipie
+  class ParamDescription
+    # Data transfer object, used when param description is deprecated
+    class Deprecation
+      attr_reader :info, :deprecated_in, :sunset_at
+
+      def initialize(info: nil, deprecated_in: nil, sunset_at: nil)
+        @info = info
+        @deprecated_in = deprecated_in
+        @sunset_at = sunset_at
+      end
+
+      def to_json(*_args)
+        {
+          info: @info,
+          deprecated_in: @deprecated_in,
+          sunset_at: @sunset_at
+        }
+      end
+    end
+  end
+end

spec/controllers/users_controller_spec.rb

@@ -269,6 +269,7 @@ def reload_controllers
                                   :allow_blank => false,
                                   :metadata => nil,
                                   :show => true,
+                                  :deprecated => false,
                                   :expected_type => "hash",
                                   :validations => [])
           end
@@ -585,6 +586,7 @@ def reload_controllers
                      :description=>"\n<p>Authorization</p>\n",
                      :name=>"oauth",
                      :show=>true,
+                     :deprecated=>false,
                      :expected_type=>"string"},
                     {:validator=>"Must be a Hash",
                      :description=>"\n<p>Deprecated parameter not documented</p>\n",
@@ -595,15 +597,17 @@ def reload_controllers
                      :required=>false,
                      :full_name=>"legacy_param",
                      :show=>false,
+                     :deprecated=>false,
                      :params=>
                       [{:validator=>"Must be a Hash",
                         :description=>"\n<p>Param description for all methods</p>\n",
                         :expected_type=>"hash",
                         :allow_nil=>false,
-                       :allow_blank => false,
+                        :allow_blank => false,
                         :name=>"resource_param",
                         :required=>false,
                         :full_name=>"resource_param",
+                        :deprecated=>false,
                         :show=>true,
                         :params=>
                         [{:required=>true,
@@ -613,6 +617,7 @@ def reload_controllers
                           :description=>"\n<p>Username for login</p>\n",
                           :name=>"ausername", :full_name=>"resource_param[ausername]",
                           :show=>true,
+                          :deprecated=>false,
                           :expected_type=>"string"},
                          {:required=>true,
                           :allow_nil => false,
@@ -621,6 +626,7 @@ def reload_controllers
                           :description=>"\n<p>Password for login</p>\n",
                           :name=>"apassword", :full_name=>"resource_param[apassword]",
                           :show=>true,
+                          :deprecated=>false,
                           :expected_type=>"string"}
                         ]}
                       ]
@@ -631,6 +637,7 @@ def reload_controllers
                      :description=>"\n<p>Company ID</p>\n",
                      :name=>"id", :full_name=>"id",
                      :show=>true,
+                     :deprecated=>false,
                      :expected_type=>"numeric"},
        ],
         :name => 'two_urls',

spec/lib/param_description/deprecation_spec.rb

@@ -0,0 +1,31 @@
+require "spec_helper"
+
+describe Apipie::ParamDescription::Deprecation do
+  let(:info) { nil }
+  let(:deprecated_in) { nil }
+  let(:sunset_at) { nil }
+
+  let(:deprecation) do
+    described_class.new(
+      info: info,
+      deprecated_in: deprecated_in,
+      sunset_at: sunset_at
+    )
+  end
+
+  describe '#to_json' do
+    subject { deprecation.to_json }
+
+    it { is_expected.to eq({ info: nil, deprecated_in: nil, sunset_at: nil }) }
+
+    context 'when attributes are given' do
+      let(:info) { 'info' }
+      let(:deprecated_in) { '2.3' }
+      let(:sunset_at) { '3.0' }
+
+      it 'returns the correct attributes' do
+        expect(subject).to eq({ info: info, deprecated_in: deprecated_in, sunset_at: sunset_at })
+      end
+    end
+  end
+end

spec/lib/param_description_spec.rb

@@ -428,4 +428,82 @@
     end
   end
 
+  describe '#deprecated?' do
+    subject do
+      Apipie::ParamDescription.new(method_desc, :param, Integer, options)
+    end
+
+    let(:options) { {} }
+
+    it { is_expected.not_to be_deprecated }
+
+    context 'when deprecated option is passed' do
+      context 'and is true' do
+        let(:options) { { deprecated: true } }
+
+        it { is_expected.to be_deprecated }
+      end
+
+      context 'and is false' do
+        let(:options) { { deprecated: false } }
+
+        it { is_expected.not_to be_deprecated }
+      end
+
+      context 'and is a string' do
+        let(:options) { { deprecated: 'Some description' } }
+
+        it { is_expected.to be_deprecated }
+      end
+
+      context 'and deprecation options are given' do
+        let(:options) do
+          { deprecated: { in: '2.3', info: 'Something', sunset: '3.0' } }
+        end
+
+        it { is_expected.to be_deprecated }
+      end
+    end
+  end
+
+  describe '#deprecation' do
+    subject { param_description.deprecation }
+
+    let(:options) { {} }
+
+    let(:param_description) do
+      Apipie::ParamDescription.new(method_desc, :param, Integer, options)
+    end
+
+    it { is_expected.to be_blank }
+
+    context 'when deprecated option is passed' do
+      context 'and is true' do
+        let(:options) { { deprecated: true } }
+
+        it { is_expected.to be_blank }
+      end
+
+      context 'and is false' do
+        let(:options) { { deprecated: false } }
+
+        it { is_expected.to be_blank }
+      end
+
+      context 'and is a string' do
+        let(:options) { { deprecated: 'Some description' } }
+
+        it { is_expected.to be_an_instance_of(Apipie::ParamDescription::Deprecation) }
+      end
+
+      context 'and deprecation options are given' do
+        let(:options) do
+          { deprecated: { in: '2.3', info: 'Something', sunset: '3.0' } }
+        end
+
+        it { is_expected.to be_an_instance_of(Apipie::ParamDescription::Deprecation) }
+      end
+    end
+  end
+
 end