Mark params as deprecated

Motivation

Currently there is no way to mark a parameter as deprecated. We may use the show: false and required: false to maybe indicate that an attribute is deprecated, however there is no direct way to indicate a deprecation.

Proposal

Introduce a truthy/falsy deprecated attribute for param / property, that defaults to false

For example

param :include_entities, String, deprecated: true
# or
param :include_entities, String, deprecated: { in: '2.3', info: 'Something', sunset: '3.0' }
# or
param :include_entities, String, deprecated: 'Some deprecation reason'
# or
param :include_entities, String, deprecated: false

Implementation

Although I haven't really thought this through the end I think something like this could work.

module Apipie
  class ParamDescription
     def initialize(method_description, name, validator, desc_or_options = nil, options = {}, &block)
       # ...
       @deprecated = options[:deprecated]
       # ...
     end

     def deprecated?
        @deprecated.present?
     end
  end
end

Apipie::ParamDescription.new(some_method_desc,  :include_entities, String, deprecated: true ...)

Later we could display it on template.

Some thoughts

Ideally I would like to convey four things

If an attributes is deprecated
At what point was deprecated
Some context, why it was deprecated, is there an alternative attribute we could use?, etc
Is there a sunset date or api version ?

Accepting a hash solves the above, it's not the most DSLish way, however I can't think anything better 😅

I don't see why it would not be backwards compatible.

At some point I would like to work on this feature. Any thoughts ?

Apipie / apipie-rails