apipie-rails 0.5.20 → 1.2.3

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,11 @@ en:
     headers: Headers
     header_name: Header name
     code: Code
+    returns: Returns
+    deprecated: Deprecated
+    deprecation_details: Deprecation details
+    deprecation:
+      attributes:
+        deprecated_in: Deprecated in
+        sunset_at: Sunset at
+        info: Info

data/config/locales/ko.yml

@@ -0,0 +1,31 @@
+ko:
+  apipie:
+    resources: 리소스
+    resource: 리소스
+    description: 설명
+    no_docs_found: 문서를 찾을 수 없습니다.
+    no_docs_found_descr: 해당 API에 대한 문서를 찾을 수 없습니다.
+    follow_instructions_html: 해당 컨트롤러의 설명을 %{href}를 따르세요.
+    follow_instructions_href: 자세한 설명
+    oops: 이런!!
+    resource_not_found_html: "%{resource} 리소스를 찾을 수 없습니다."
+    method_not_found_html: "%{resource} 리소스에 대한 %{method} 메소드를 찾을 수 없습니다."
+    goto_homepage_html: "%{href}로 시도해보세요."
+    goto_homepage_href: "%{app_name} API 문서 페이지"
+    required: 필수
+    optional: 옵션
+    nil_allowed: nil 허용
+    param_name: Param 이름
+    params: Params
+    examples: 예시
+    metadata: Metadata
+    errors: 에러
+    error_code: 코드
+    error_description: 설명
+    error_metadata: Metadata
+    supported_formats: 지원 포멧
+    enable_javascript_html: "%{comments_href}를 보기 위해서 JavaScript를 허용해주세요."
+    comments_powered_by_disqus: comments powered by %{disqus}
+    api_documentation: API 문서
+    headers: 헤더
+    header_name: 헤더 이름

data/gemfiles/Gemfile.tools

@@ -0,0 +1,9 @@
+# This Gemfile is used for IDEs like VS Code that need specific gems installed
+# for their tools to work properly. It is not used for the application itself.
+
+source 'https://rubygems.org'
+
+gem 'rubocop-rails'
+gem 'rubocop-rspec'
+gem 'rubocop-performance'
+gem 'ruby-lsp', '~> 0.5.1'

data/lib/apipie/apipie_module.rb

@@ -8,14 +8,14 @@ module Apipie
     @application ||= Apipie::Application.new
   end
 
-  def self.to_json(version = nil, resource_name = nil, method_name = nil, lang = nil)
+  def self.to_json(version = nil, resource_id = nil, method_name = nil, lang = nil)
     version ||= Apipie.configuration.default_version
-    app.to_json(version, resource_name, method_name, lang)
+    app.to_json(version, resource_id, method_name, lang)
   end
 
-  def self.to_swagger_json(version = nil, resource_name = nil, method_name = nil, lang = nil, clear_warnings=true)
+  def self.to_swagger_json(version = nil, resource_id = nil, method_name = nil, lang = nil, clear_warnings = true)
     version ||= Apipie.configuration.default_version
-    app.to_swagger_json(version, resource_name, method_name, lang, clear_warnings)
+    app.to_swagger_json(version, resource_id, method_name, lang, clear_warnings)
   end
 
   def self.json_schema_for_method_response(controller_name, method_name, return_code, allow_nulls)
@@ -24,7 +24,7 @@ module Apipie
     app.json_schema_for_method_response(version, controller_name, method_name, return_code, allow_nulls)
   end
 
-  def self.json_schema_for_self_describing_class(cls, allow_nulls=true)
+  def self.json_schema_for_self_describing_class(cls, allow_nulls = true)
     app.json_schema_for_self_describing_class(cls, allow_nulls)
   end
 
@@ -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

@@ -25,49 +25,46 @@ module Apipie
       @resource_descriptions.keys.sort
     end
 
-    def set_resource_id(controller, resource_id)
-      @controller_to_resource_id[controller] = resource_id
-    end
-
     def rails_routes(route_set = nil, base_url = "")
-      if route_set.nil? && @rails_routes
-        return @rails_routes
-      end
+      return @_rails_routes if route_set.nil? && @_rails_routes
+
       route_set ||= Rails.application.routes
       # ensure routes are loaded
       Rails.application.reload_routes! unless Rails.application.routes.routes.any?
 
-      flatten_routes = []
+      flattened_routes = []
 
       route_set.routes.each do |route|
-        # This is a hack to workaround a bug in apipie with Rails 4.2.5.1 or newer. See https://github.com/Apipie/apipie-rails/issues/415
-        route_app = Rails::VERSION::STRING.to_f >= 4.2 ? route.app.app : route.app
+        # route is_a ActionDispatch::Journey::Route
+        # route.app is_a ActionDispatch::Routing::Mapper::Constraints
+        # route.app.app is_a TestEngine::Engine
+        route_app = route.app.app
         if route_app.respond_to?(:routes) && route_app.routes.is_a?(ActionDispatch::Routing::RouteSet)
           # recursively go though the mounted engines
-          flatten_routes.concat(rails_routes(route_app.routes, File.join(base_url, route.path.spec.to_s)))
+          flattened_routes.concat(rails_routes(route_app.routes, File.join(base_url, route.path.spec.to_s)))
         else
           route.base_url = base_url
-          flatten_routes << route
+          flattened_routes << route
         end
       end
 
-      @rails_routes = flatten_routes
+      @_rails_routes = flattened_routes
     end
 
-    # the app might be nested when using contraints, namespaces etc.
-    # this method does in depth search for the route controller
-    def route_app_controller(app, route, visited_apps = [])
-      if route.defaults[:controller]
-        controller_name = "#{route.defaults[:controller]}_controller".camelize
-        controller_name.safe_constantize
+    def rails_routes_by_controller_and_action
+      @_rails_routes_by_controller_and_action = rails_routes.group_by do |route|
+        requirements = route.requirements
+        [requirements[:controller], requirements[:action]]
       end
     end
 
+    def clear_cached_routes!
+      @_rails_routes = nil
+      @_rails_routes_by_controller_and_action = nil
+    end
+
     def routes_for_action(controller, method, args)
-      routes = rails_routes.select do |route|
-        controller == route_app_controller(route.app, route) &&
-            method.to_s == route.defaults[:action]
-      end
+      routes = rails_routes_by_controller_and_action[[controller.name.underscore.chomp('_controller'), method.to_s]] || []
 
       Apipie.configuration.routes_formatter.format_routes(routes, args)
     end
@@ -81,8 +78,8 @@ module Apipie
       versions = controller_versions(controller) if versions.empty?
 
       versions.each do |version|
-        resource_name_with_version = "#{version}##{get_resource_name(controller)}"
-        resource_description = get_resource_description(resource_name_with_version)
+        resource_id_with_version = "#{version}##{get_resource_id(controller)}"
+        resource_description = get_resource_description(resource_id_with_version)
 
         if resource_description.nil?
           resource_description = define_resource_description(controller, version)
@@ -98,24 +95,24 @@ module Apipie
         resource_description.add_method_description(method_description)
       end
 
-      return ret_method_description
+      ret_method_description
     end
 
     # create new resource api description
     def define_resource_description(controller, version, dsl_data = nil)
       return if ignored?(controller)
 
-      resource_name = get_resource_name(controller)
-      resource_description = @resource_descriptions[version][resource_name]
+      resource_id = get_resource_id(controller)
+      resource_description = @resource_descriptions[version][resource_id]
       if resource_description
         # we already defined the description somewhere (probably in
         # some method. Updating just meta data from dsl
         resource_description.update_from_dsl_data(dsl_data) if dsl_data
       else
-        resource_description = Apipie::ResourceDescription.new(controller, resource_name, dsl_data, version)
+        resource_description = Apipie::ResourceDescription.new(controller, resource_id, dsl_data, version)
 
-        Apipie.debug("@resource_descriptions[#{version}][#{resource_name}] = #{resource_description}")
-        @resource_descriptions[version][resource_name] ||= resource_description
+        Apipie.debug("@resource_descriptions[#{version}][#{resource_id}] = #{resource_description}")
+        @resource_descriptions[version][resource_id] ||= resource_description
       end
 
       return resource_description
@@ -125,15 +122,26 @@ module Apipie
     # resource_description? It's used to derivate the default value of
     # versions for methods.
     def controller_versions(controller)
-      ret = @controller_versions[controller.to_s]
-      return ret unless ret.empty?
-      if controller == ActionController::Base || controller.nil?
-        return [Apipie.configuration.default_version]
-      else
-        return controller_versions(controller.to_s.constantize.superclass)
+      value_from_parents(controller, default: [Apipie.configuration.default_version]) do |c|
+        ret = @controller_versions[c.to_s]
+        ret unless ret.empty?
       end
     end
 
+    # Recursively walks up the controller hierarchy looking for a value
+    # from the block.
+    # Stops at ActionController::Base.
+    # @param [Class] controller controller to start from
+    # @param [Array] args arguments passed to the block
+    # @param [Object] default default value to return if no value is found
+    # @param [Proc] block block to call with controller and args
+    def value_from_parents(controller, *args, default: nil, &block)
+      return default if controller == ActionController::Base || controller == AbstractController::Base || controller.nil?
+
+      thing = yield(controller, *args)
+      thing || value_from_parents(controller.superclass, *args, default: default, &block)
+    end
+
     def set_controller_versions(controller, versions)
       @controller_versions[controller.to_s] = versions
     end
@@ -145,7 +153,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"
@@ -156,34 +164,32 @@ module Apipie
     #
     # There are two ways how this method can be used:
     # 1) Specify both parameters
-    #   resource_name:
+    #   resource_id:
     #       controller class - UsersController
     #       string with resource name (plural) and version - "v1#users"
     #   method_name: name of the method (string or symbol)
     #
     # 2) Specify only first parameter:
-    #   resource_name: string containing both resource and method name joined
+    #   resource_id: string containing both resource and method name joined
     #   with '#' symbol.
     #   - "users#create" get default version
     #   - "v2#users#create" get specific version
-    def get_method_description(resource_name, method_name = nil)
-      if resource_name.is_a?(String)
-        crumbs = resource_name.split('#')
+    def get_method_description(resource_id, method_name = nil)
+      if resource_id.is_a?(String)
+        crumbs = resource_id.split('#')
         if method_name.nil?
           method_name = crumbs.pop
         end
-        resource_name = crumbs.join("#")
-        resource_description = get_resource_description(resource_name)
-      elsif resource_name.respond_to? :apipie_resource_descriptions
-        resource_description = get_resource_description(resource_name)
+        resource_id = crumbs.join("#")
+        resource_description = get_resource_description(resource_id)
+      elsif resource_id.respond_to? :apipie_resource_descriptions
+        resource_description = get_resource_description(resource_id)
       else
-        raise ArgumentError.new("Resource #{resource_name} does not exists.")
-      end
-      unless resource_description.nil?
-        resource_description.method_description(method_name.to_sym)
+        raise ArgumentError.new("Resource #{resource_id} does not exists.")
       end
+      resource_description&.method_description(method_name.to_sym)
     end
-    alias :[] :get_method_description
+    alias [] get_method_description
 
     # options:
     # => "users"
@@ -196,19 +202,19 @@ 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
-        resource_name = get_resource_name(resource)
+        resource_id = get_resource_id(resource)
         if version
-          resource_name = "#{version}##{resource_name}"
+          resource_id = "#{version}##{resource_id}"
         end
 
-        if resource_name.nil?
+        if resource_id.nil?
           return nil
         end
-        resource_description = get_resource_description(resource_name)
+        resource_description = get_resource_description(resource_id)
         if resource_description && resource_description.controller.to_s == resource.to_s
           return resource_description
         end
@@ -231,7 +237,7 @@ module Apipie
 
     def remove_method_description(resource, versions, method_name)
       versions.each do |version|
-        resource = get_resource_name(resource)
+        resource = get_resource_id(resource)
         if resource_description = get_resource_description("#{version}##{resource}")
           resource_description.remove_method_description(method_name)
         end
@@ -240,13 +246,12 @@ module Apipie
 
     # initialize variables for gathering dsl data
     def init_env
-      @resource_descriptions ||= HashWithIndifferentAccess.new { |h, version| h[version] = {} }
-      @controller_to_resource_id ||= {}
-      @param_groups ||= {}
-      @swagger_generator = Apipie::SwaggerGenerator.new(self)
+      @resource_descriptions = ActiveSupport::HashWithIndifferentAccess.new { |h, version| h[version] = {} }
+      @controller_to_resource_id = {}
+      @param_groups = {}
 
       # what versions does the controller belong in (specified by resource_description)?
-      @controller_versions ||= Hash.new { |h, controller| h[controller.to_s] = [] }
+      @controller_versions = Hash.new { |h, controller| h[controller.to_s] = [] }
     end
 
     def recorded_examples
@@ -261,36 +266,41 @@ module Apipie
     def json_schema_for_method_response(version, controller_name, method_name, return_code, allow_nulls)
       method = @resource_descriptions[version][controller_name].method_description(method_name)
       raise NoDocumentedMethod.new(controller_name, method_name) if method.nil?
-      @swagger_generator.json_schema_for_method_response(method, return_code, allow_nulls)
+
+      Apipie::SwaggerGenerator
+        .json_schema_for_method_response(method, return_code, allow_nulls)
     end
 
     def json_schema_for_self_describing_class(cls, allow_nulls)
-      @swagger_generator.json_schema_for_self_describing_class(cls, allow_nulls)
+      Apipie::SwaggerGenerator
+        .json_schema_for_self_describing_class(cls, allow_nulls)
     end
 
-    def to_swagger_json(version, resource_name, method_name, lang, clear_warnings=false)
-      return unless valid_search_args?(version, resource_name, method_name)
+    def to_swagger_json(version, resource_id, method_name, language, clear_warnings = false)
+      return unless valid_search_args?(version, resource_id, method_name)
 
-      # if resource_name is blank, take just resources which have some methods because
-      # we dont want to show eg ApplicationController as resource
-      # otherwise, take only the specified resource
-      _resources = resource_descriptions[version].inject({}) do |result, (k,v)|
-         if resource_name.blank?
-           result[k] = v unless v._methods.blank?
-         else
-           result[k] = v if k == resource_name
-         end
-         result
-       end
+      resources =
+        Apipie::Generator::Swagger::ResourceDescriptionsCollection
+        .new(resource_descriptions)
+        .filter(
+          resource_id: resource_id,
+          method_name: method_name,
+          version: version
+        )
 
-      @swagger_generator.generate_from_resources(version,_resources, method_name, lang, clear_warnings)
+      Apipie::SwaggerGenerator.generate_from_resources(
+        resources,
+        version: version,
+        language: language,
+        clear_warnings: clear_warnings
+      )
     end
 
-    def to_json(version, resource_name, method_name, lang)
+    def to_json(version, resource_id, method_name, lang)
 
-      return unless valid_search_args?(version, resource_name, method_name)
+      return unless valid_search_args?(version, resource_id, method_name)
 
-      _resources = if resource_name.blank?
+      _resources = if resource_id.blank?
         # take just resources which have some methods because
         # we dont want to show eg ApplicationController as resource
         resource_descriptions[version].inject({}) do |result, (k,v)|
@@ -298,7 +308,7 @@ module Apipie
           result
         end
       else
-        [@resource_descriptions[version][resource_name].to_json(method_name, lang)]
+        [@resource_descriptions[version][resource_id].to_json(method_name, lang)]
       end
 
       url_args = Apipie.configuration.version_in_url ? version : ''
@@ -368,15 +378,39 @@ module Apipie
       Apipie.configuration.validate? || ! Apipie.configuration.use_cache? || Apipie.configuration.force_dsl?
     end
 
+    # @deprecated Use {#get_resource_id} instead
     def get_resource_name(klass)
+      ActiveSupport::Deprecation.warn(
+        <<~HEREDOC
+          Apipie::Application.get_resource_name is deprecated.
+          Use `Apipie::Application.get_resource_id instead.
+        HEREDOC
+      )
+
+      get_resource_id(klass)
+    end
+
+    def set_resource_id(controller, resource_id)
+      @controller_to_resource_id[controller] = resource_id
+    end
+
+    def get_resource_id(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
+
+        version_prefix = version_prefix(klass)
         path = klass.controller_path
-        path.gsub(version_prefix(klass), "").gsub("/", "-")
+
+        unless version_prefix == '/'
+          path =
+            path.gsub(version_prefix, '')
+        end
+
+        path.gsub('/', '-')
       elsif klass.respond_to?(:controller_name)
         return nil if klass == ActionController::Base
         klass.controller_name
@@ -386,11 +420,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)
@@ -403,14 +437,14 @@ module Apipie
 
     private
 
-    # 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)
-      if resource_name
-        return false unless self.resource_descriptions[version].has_key?(resource_name)
+    # Make sure that the version/resource_id/method_name are valid combination
+    # resource_id and method_name can be nil
+    def valid_search_args?(version, resource_id, method_name)
+      return false unless self.resource_descriptions.key?(version)
+      if resource_id
+        return false unless self.resource_descriptions[version].key?(resource_id)
         if method_name
-          resource_description = self.resource_descriptions[version][resource_name]
+          resource_description = self.resource_descriptions[version][resource_id]
           return false unless resource_description.valid_method_name?(method_name)
         end
       end
@@ -418,7 +452,7 @@ module Apipie
     end
 
     def version_prefix(klass)
-      version = controller_versions(klass.to_s).first
+      version = controller_versions(klass).first
       base_url = get_base_url(version)
       return "/" if base_url.blank?
       base_url[1..-1] + "/"
@@ -456,10 +490,11 @@ module Apipie
     # as this would break loading of the controllers.
     def rails_mark_classes_for_reload
       unless Rails.application.config.cache_classes
-        Rails::VERSION::MAJOR == 4 ? ActionDispatch::Reloader.cleanup! : Rails.application.reloader.reload!
+        clear_cached_routes!
+        Rails.application.reloader.reload!
         init_env
         reload_examples
-        Rails::VERSION::MAJOR == 4 ? ActionDispatch::Reloader.prepare! : Rails.application.reloader.prepare!
+        Rails.application.reloader.prepare!
       end
     end