apipie-rails 0.9.1 → 0.9.3

data/CHANGELOG.md

@@ -4,6 +4,23 @@
 Also deleted the `Gemfile` that was now a broken symlink.
 please use `export BUNDLE_GEMFILE='gemfiles/Gemfile.rails61'; bundle exec rspec` to run the test suite
 
+## [v0.9.3](https://github.com/Apipie/apipie-rails/tree/v0.9.3) (2023-03-08)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.9.2...v0.9.3)
+* [Feature] Allow Apipie::ParamDescription to be marked as deprecated [#819](https://github.com/Apipie/apipie-rails/pull/819)[#811](https://github.com/Apipie/apipie-rails/pull/811) (Panos Dalitsouris)
+* [Fix] Make html markup thread safe ([#822](https://github.com/Apipie/apipie-rails/issues/822)) (Adam Růžička)
+* [Feature] Allow action matcher strategy to be configured [#821](https://github.com/Apipie/apipie-rails/pull/821) (Panos Dalitsouris)
+* [CI] Run Rubocop when opening PR [#826](https://github.com/Apipie/apipie-rails/pull/826) (Panos Dalitsouris)
+* [CI] Green rubocop - Fix after rubocop challenger upgrade [#829](https://github.com/Apipie/apipie-rails/pull/829) (Mathieu Jobin)
+* [Rubocop] More Rubocop Auto corrections [#818](https://github.com/Apipie/apipie-rails/pull/818)[#825](https://github.com/Apipie/apipie-rails/pull/825)[#827](https://github.com/Apipie/apipie-rails/pull/827)[#837](https://github.com/Apipie/apipie-rails/pull/837)[#839](https://github.com/Apipie/apipie-rails/pull/839) (Rubocop Challenger)
+
+## [v0.9.2](https://github.com/Apipie/apipie-rails/tree/v0.9.2) (2023-02-07)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.9.1...v0.9.2)
+* [Rubocop] More Rubocop Auto corrections [#795](https://github.com/Apipie/apipie-rails/pull/795)[#781](https://github.com/Apipie/apipie-rails/pull/781)[#791](https://github.com/Apipie/apipie-rails/pull/791)[#788](https://github.com/Apipie/apipie-rails/pull/788) (Rubocop Challenger)
+* [Fix] Can't include translation in full description ([#446](https://github.com/Apipie/apipie-rails/issues/446)) [#808](https://github.com/Apipie/apipie-rails/pull/808) (Peter Nagy)
+* [Refactor] Move swagger param description creation [#810](https://github.com/Apipie/apipie-rails/pull/810) (Panos Dalitsouris)
+* [Rubocop] Redo rubocop TODOs, set HashSyntax config to most used style [#814](https://github.com/Apipie/apipie-rails/pull/814) (Mathieu Jobin)
+* [Fix] Swagger missing i18n [#815](https://github.com/Apipie/apipie-rails/pull/815) (@jirubio)
+
 ## [v0.9.1](https://github.com/Apipie/apipie-rails/tree/v0.9.1) (2023-01-16)
 [Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.9.0...v0.9.1)
 * [Refactor] Create test cache files under a not version controlled directory [#809](https://github.com/Apipie/apipie-rails/pull/809) (Panos Dalitsouris)

data/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
 --------------------
 
@@ -982,6 +998,9 @@ reload_controllers
 api_controllers_matcher
   For reloading to work properly you need to specify where your API controllers are. Can be an array if multiple paths are needed
 
+api_action_matcher
+  Determines the strategy to identity the correct controller action. Needs to be a class that implements a `.call(controller)` method
+
 api_routes
   Set if your application uses a custom API router, different from the Rails
   default
@@ -1063,6 +1082,7 @@ Example:
      config.markup = Apipie::Markup::Markdown.new
      config.reload_controllers = Rails.env.development?
      config.api_controllers_matcher = File.join(Rails.root, "app", "controllers", "**","*.rb")
+     config.api_action_matcher = proc { |controller| controller.params[:action] }
      config.api_routes = Rails.application.routes
      config.app_info["1.0"] = "
        This is where you can inform user about your application and API

data/apipie-rails.gemspec

@@ -1,4 +1,5 @@
 # -*- encoding: utf-8 -*-
+
 $:.push File.expand_path('lib', __dir__)
 require "apipie/version"
 
@@ -28,6 +29,9 @@ Gem::Specification.new do |s|
   s.add_development_dependency "rspec-rails", "~> 3.0"
   s.add_development_dependency "rake"
   s.add_development_dependency 'rubocop_challenger'
+  s.add_development_dependency 'rubocop-rails'
+  s.add_development_dependency 'rubocop-rspec'
+  s.add_development_dependency 'rubocop-performance'
   s.add_development_dependency "simplecov"
   s.add_development_dependency "sqlite3"
 end

data/app/controllers/apipie/apipies_controller.rb

@@ -98,12 +98,11 @@ module Apipie
       return nil unless Apipie.configuration.translate
       lang = Apipie.configuration.default_locale
       [:resource, :method, :version].each do |par|
-        if params[par]
-          splitted = params[par].split('.')
-          if splitted.length > 1 && (Apipie.configuration.languages.include?(splitted.last) || Apipie.configuration.default_locale == splitted.last)
-            lang = splitted.last
-            params[par].sub!(".#{lang}", '')
-          end
+        next unless params[par]
+        splitted = params[par].split('.')
+        if splitted.length > 1 && (Apipie.configuration.languages.include?(splitted.last) || Apipie.configuration.default_locale == splitted.last)
+          lang = splitted.last
+          params[par].sub!(".#{lang}", '')
         end
       end
       lang

data/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 %>

data/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:

data/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

data/lib/apipie/apipie_module.rb

@@ -70,11 +70,11 @@ module Apipie
   end
 
   def self.app_info_version_valid?(version)
-    version && self.configuration.app_info.has_key?(version)
+    version && self.configuration.app_info.key?(version)
   end
 
   def self.api_base_url_version_valid?(version)
-    version && self.configuration.api_base_url.has_key?(version)
+    version && self.configuration.api_base_url.key?(version)
   end
 
   def self.record(record)

data/lib/apipie/application.rb

@@ -147,7 +147,7 @@ module Apipie
 
     def get_param_group(controller, name)
       key = "#{controller.name}##{name}"
-      if @param_groups.has_key?(key)
+      if @param_groups.key?(key)
         return @param_groups[key]
       else
         raise "param group #{key} not defined"
@@ -181,11 +181,9 @@ module Apipie
       else
         raise ArgumentError.new("Resource #{resource_name} does not exists.")
       end
-      unless resource_description.nil?
-        resource_description.method_description(method_name.to_sym)
-      end
+      resource_description&.method_description(method_name.to_sym)
     end
-    alias :[] :get_method_description
+    alias [] get_method_description
 
     # options:
     # => "users"
@@ -198,7 +196,7 @@ module Apipie
           version = crumbs.first
         end
         version ||= Apipie.configuration.default_version
-        if @resource_descriptions.has_key?(version)
+        if @resource_descriptions.key?(version)
           return @resource_descriptions[version][crumbs.last]
         end
       else
@@ -242,7 +240,7 @@ module Apipie
 
     # initialize variables for gathering dsl data
     def init_env
-      @resource_descriptions = HashWithIndifferentAccess.new { |h, version| h[version] = {} }
+      @resource_descriptions = ActiveSupport::HashWithIndifferentAccess.new { |h, version| h[version] = {} }
       @controller_to_resource_id = {}
       @param_groups = {}
       @swagger_generator = Apipie::SwaggerGenerator.new(self)
@@ -373,7 +371,7 @@ module Apipie
     def get_resource_name(klass)
       if klass.class == String
         klass
-      elsif @controller_to_resource_id.has_key?(klass)
+      elsif @controller_to_resource_id.key?(klass)
         @controller_to_resource_id[klass]
       elsif Apipie.configuration.namespaced_resources? && klass.respond_to?(:controller_path)
         return nil if klass == ActionController::Base
@@ -388,11 +386,11 @@ module Apipie
     end
 
     def locale
-      Apipie.configuration.locale.call(nil) if Apipie.configuration.locale
+      Apipie.configuration.locale&.call(nil)
     end
 
     def locale=(locale)
-      Apipie.configuration.locale.call(locale) if Apipie.configuration.locale
+      Apipie.configuration.locale&.call(locale)
     end
 
     def translate(str, locale)
@@ -408,9 +406,9 @@ module Apipie
     # Make sure that the version/resource_name/method_name are valid combination
     # resource_name and method_name can be nil
     def valid_search_args?(version, resource_name, method_name)
-      return false unless self.resource_descriptions.has_key?(version)
+      return false unless self.resource_descriptions.key?(version)
       if resource_name
-        return false unless self.resource_descriptions[version].has_key?(resource_name)
+        return false unless self.resource_descriptions[version].key?(resource_name)
         if method_name
           resource_description = self.resource_descriptions[version][resource_name]
           return false unless resource_description.valid_method_name?(method_name)

data/lib/apipie/configuration.rb

@@ -14,19 +14,29 @@ module Apipie
       :swagger_allow_additional_properties_in_response, :swagger_responses_use_refs,
       :swagger_schemes, :swagger_security_definitions, :swagger_global_security
 
-    alias_method :validate?, :validate
-    alias_method :required_by_default?, :required_by_default
-    alias_method :namespaced_resources?, :namespaced_resources
-    alias_method :swagger_include_warning_tags?, :swagger_include_warning_tags
-    alias_method :swagger_json_input_uses_refs?, :swagger_json_input_uses_refs
-    alias_method :swagger_responses_use_refs?, :swagger_responses_use_refs
-    alias_method :swagger_generate_x_computed_id_field?, :swagger_generate_x_computed_id_field
+    alias validate? validate
+    alias required_by_default? required_by_default
+    alias namespaced_resources? namespaced_resources
+    alias swagger_include_warning_tags? swagger_include_warning_tags
+    alias swagger_json_input_uses_refs? swagger_json_input_uses_refs
+    alias swagger_responses_use_refs? swagger_responses_use_refs
+    alias swagger_generate_x_computed_id_field? swagger_generate_x_computed_id_field
 
     # matcher to be used in Dir.glob to find controllers to be reloaded e.g.
     #
     #   "#{Rails.root}/app/controllers/api/*.rb"
     attr_accessor :api_controllers_matcher
 
+    # An object that responds to a `.call(controller)` method responsible for
+    # matching the correct controller action
+    attr_reader :api_action_matcher
+
+    def api_action_matcher=(callable)
+      raise 'Must implement .call method' unless callable.respond_to?(:call)
+
+      @api_action_matcher = callable
+    end
+
     # set to true if you want to reload the controllers at each refresh of the
     # documentation. It requires +:api_controllers_matcher+ to be set to work
     # properly.
@@ -51,17 +61,17 @@ module Apipie
     def validate_value
       return (validate? && @validate_value)
     end
-    alias_method :validate_value?, :validate_value
+    alias validate_value? validate_value
 
     def validate_presence
       return (validate? && @validate_presence)
     end
-    alias_method :validate_presence?, :validate_presence
+    alias validate_presence? validate_presence
 
     def validate_key
       return (validate? && @validate_key)
     end
-    alias_method :validate_key?, :validate_key
+    alias validate_key? validate_key
 
     def process_value?
       @process_params
@@ -73,7 +83,7 @@ module Apipie
     #
     #     rake apipie:cache
     attr_accessor :use_cache
-    alias_method :use_cache?, :use_cache
+    alias use_cache? use_cache
 
     attr_writer :cache_dir
     def cache_dir
@@ -147,7 +157,7 @@ module Apipie
     def initialize
       @markup = Apipie::Markup::RDoc.new
       @app_name = "Another API"
-      @app_info = HashWithIndifferentAccess.new
+      @app_info = ActiveSupport::HashWithIndifferentAccess.new
       @copyright = nil
       @validate = :implicitly
       @validate_value = true
@@ -155,7 +165,8 @@ module Apipie
       @validate_key = false
       @action_on_non_validated_keys = :raise
       @required_by_default = false
-      @api_base_url = HashWithIndifferentAccess.new
+      @api_base_url = ActiveSupport::HashWithIndifferentAccess.new
+      @api_action_matcher = proc { |controller| controller.params[:action] }
       @doc_base_url = "/apipie"
       @layout = "apipie/apipie"
       @disqus_shortname = nil

data/lib/apipie/dsl_definition.rb

@@ -70,7 +70,7 @@ module Apipie
       def short(short)
         _apipie_dsl_data[:short_description] = short
       end
-      alias :short_description :short
+      alias short_description short
 
       def path(path)
         _apipie_dsl_data[:path] = path
@@ -145,7 +145,7 @@ module Apipie
       # EOS
       def resource_description(options = {}, &block) #:doc:
         return unless Apipie.active_dsl?
-        raise ArgumentError, "Block expected" unless block_given?
+        raise ArgumentError, "Block expected" unless block
 
         dsl_data = ResourceDescriptionDsl.eval_dsl(self, &block)
         versions = dsl_data[:api_versions]
@@ -160,7 +160,7 @@ module Apipie
       def api_versions(*versions)
         _apipie_dsl_data[:api_versions].concat(versions)
       end
-      alias :api_version :api_versions
+      alias api_version api_versions
 
       # Describe the next method.
       #
@@ -177,8 +177,8 @@ module Apipie
         end
         _apipie_dsl_data[:description] = description
       end
-      alias :description :desc
-      alias :full_description :desc
+      alias description desc
+      alias full_description desc
 
       # describe next method with document in given path
       # in convension, these doc located under "#{Rails.root}/doc"
@@ -246,14 +246,14 @@ module Apipie
               if Apipie.configuration.validate_presence?
                 method_params.each do |_, param|
                   # check if required parameters are present
-                  raise ParamMissing.new(param) if param.required && !params.has_key?(param.name)
+                  raise ParamMissing.new(param) if param.required && !params.key?(param.name)
                 end
               end
 
               if Apipie.configuration.validate_value?
                 method_params.each do |_, param|
                   # params validations
-                  param.validate(params[:"#{param.name}"]) if params.has_key?(param.name)
+                  param.validate(params[:"#{param.name}"]) if params.key?(param.name)
                 end
               end
 
@@ -272,7 +272,7 @@ module Apipie
                 @api_params ||= {}
                 method_params.each do |_, param|
                   # params processing
-                  @api_params[param.as] = param.process_value(params[:"#{param.name}"]) if params.has_key?(param.name)
+                  @api_params[param.as] = param.process_value(params[:"#{param.name}"]) if params.key?(param.name)
                 end
               end
             end
@@ -293,9 +293,10 @@ module Apipie
       end
 
       def _apipie_handle_validate_key_error params, param
-        if Apipie.configuration.action_on_non_validated_keys == :raise
+        case Apipie.configuration.action_on_non_validated_keys
+        when :raise
           raise UnknownParam, param
-        elsif Apipie.configuration.action_on_non_validated_keys == :skip
+        when :skip
           params.delete(param)
           Rails.logger.warn(UnknownParam.new(param).to_s)
         end
@@ -507,7 +508,7 @@ module Apipie
       end
 
       def _apipie_update_meta(method_desc, dsl_data)
-        return unless dsl_data[:meta] && dsl_data[:meta].is_a?(Hash)
+        return unless dsl_data[:meta].is_a?(Hash)
 
         method_desc.metadata ||= {}
         method_desc.metadata.merge!(dsl_data[:meta])
@@ -525,7 +526,7 @@ module Apipie
         end
       end
       # backwards compatibility
-      alias_method :apipie_update_params, :apipie_update_methods
+      alias apipie_update_params apipie_update_methods
 
       def _apipie_concern_subst
         @_apipie_concern_subst ||= {:controller_path => self.controller_path,

data/lib/apipie/error_description.rb

@@ -31,10 +31,10 @@ module Apipie
       end
     end
 
-    def to_json
+    def to_json(lang)
       {
         :code => code,
-        :description => description,
+        :description => Apipie.app.translate(description, lang),
         :metadata => metadata
       }
     end

data/lib/apipie/extractor/recorder.rb

@@ -24,7 +24,7 @@ module Apipie
 
       def analyse_controller(controller)
         @controller = controller.class
-        @action = controller.params[:action]
+        @action = Apipie.configuration.api_action_matcher.call(controller)
       end
 
       def analyse_response(response)

data/lib/apipie/extractor/writer.rb

@@ -103,7 +103,7 @@ module Apipie
         call = call.stringify_keys
         ordered_call = OrderedHash.new
         %w[title verb path versions query request_data response_data code show_in_doc recorded].each do |k|
-          next unless call.has_key?(k)
+          next unless call.key?(k)
           ordered_call[k] = case call[k]
                      when ActiveSupport::HashWithIndifferentAccess
                        convert_file_value(call[k]).to_hash
@@ -116,9 +116,10 @@ module Apipie
 
       def convert_file_value hash
         hash.each do |k, v|
-          if v.is_a?(Rack::Test::UploadedFile) || v.is_a?(ActionDispatch::Http::UploadedFile)
+          case v
+          when Rack::Test::UploadedFile, ActionDispatch::Http::UploadedFile
             hash[k] = "<FILE CONTENT '#{v.original_filename}'>"
-          elsif v.is_a?(Hash)
+          when Hash
             hash[k] = convert_file_value(v)
           end
         end
@@ -134,8 +135,8 @@ module Apipie
         old_examples = self.load_recorded_examples
         merged_examples = []
         (new_examples.keys + old_examples.keys).uniq.each do |key|
-          if new_examples.has_key?(key)
-            if old_examples.has_key?(key)
+          if new_examples.key?(key)
+            if old_examples.key?(key)
               records = deep_merge_examples(new_examples[key], old_examples[key])
             else
               records = new_examples[key]
@@ -407,12 +408,11 @@ module Apipie
           if line =~ /\s*\b(module|class|def)\b /
             break
           end
-          if line =~ /do\s*(\|.*?\|)?\s*$/
-            block_level -= 1
-            if block_level == 0
-              added_lines.concat(lines_to_add)
-              lines_to_add = []
-            end
+          next unless line =~ /do\s*(\|.*?\|)?\s*$/
+          block_level -= 1
+          if block_level == 0
+            added_lines.concat(lines_to_add)
+            lines_to_add = []
           end
         end
         return added_lines.reverse.join

data/lib/apipie/extractor.rb

@@ -157,7 +157,7 @@ module Apipie
           method_key = "#{Apipie.get_resource_name(controller.safe_constantize || next)}##{action}"
           old_apis = apis_from_docs[method_key] || []
           new_apis.each do |new_api|
-            new_api[:path].sub!(/\(\.:format\)$/,"") if new_api[:path]
+            new_api[:path]&.sub!(/\(\.:format\)$/,"")
             old_api = old_apis.find do |api|
               api[:path] == "#{@api_prefix}#{new_api[:path]}"
             end

data/lib/apipie/generator/swagger/context.rb

@@ -0,0 +1,27 @@
+class Apipie::Generator::Swagger::Context
+  attr_reader :default_in_value, :language, :http_method, :controller_method
+
+  def initialize(
+    allow_null:,
+    http_method:,
+    controller_method:,
+    default_in_value: nil,
+    language: nil,
+    in_schema: true
+  )
+    @default_in_value = default_in_value
+    @allow_null = allow_null
+    @language = language
+    @in_schema = in_schema
+    @http_method = http_method
+    @controller_method = controller_method
+  end
+
+  def allow_null?
+    @allow_null == true
+  end
+
+  def in_schema?
+    @in_schema == true
+  end
+end

data/lib/apipie/generator/swagger/operation_id.rb

@@ -0,0 +1,51 @@
+class Apipie::Generator::Swagger::OperationId
+  def initialize(path:, http_method:, param: nil)
+    @path = path
+    @http_method = http_method
+    @param = param
+  end
+
+  # @return [String]
+  def to_s
+    base = normalized_http_method + path
+
+    if @param.present?
+      "#{base}_param_#{@param}"
+    else
+      base
+    end
+  end
+
+  # @param [Apipie::MethodDescription::Api, Apipie::MethodDescription] describable
+  # @param [String, Symbol, nil] param
+  #
+  # @return [Apipie::Generator::Swagger::OperationId]
+  def self.from(describable, param: nil)
+    path, http_method =
+      if describable.is_a?(Apipie::MethodDescription::Api)
+        [describable.path, describable.http_method]
+      elsif describable.is_a?(Apipie::MethodDescription)
+        [describable.apis.first.path, describable.apis.first.http_method]
+      end
+
+    new(path: path, http_method: http_method, param: param)
+  end
+
+  private
+
+  # Converts an http path for example `/api/concerns/:id` to `_api_concerns_id`
+  #
+  # @return [String]
+  def path
+    @path.gsub(/\//, '_').gsub(/:(\w+)/, '\1').gsub(/_$/, '')
+  end
+
+  # Converts an http method like `GET` to `get` Using lowercase http method,
+  #   because the 'swagger-codegen' tool outputs strange method names if the
+  #   http method is in uppercase
+  #
+  # @return [String]
+  def normalized_http_method
+    @http_method.to_s.downcase
+  end
+end