apipie-rails-jq 1.4.3.pre.beta.pre.jq.1

data/lib/apipie/application.rb

@@ -0,0 +1,499 @@
+require 'apipie/static_dispatcher'
+require 'apipie/routes_formatter'
+require 'yaml'
+require 'digest/sha1'
+require 'json'
+
+module Apipie
+
+  class Application
+    # we need engine just for serving static assets
+    class Engine < Rails::Engine
+      initializer "static assets", :before => :build_middleware_stack do |app|
+        app.middleware.use ::Apipie::StaticDispatcher, "#{root}/app/public"
+      end
+    end
+
+    attr_reader :resource_descriptions
+
+    def initialize
+      super
+      init_env
+    end
+
+    def available_versions
+      @resource_descriptions.keys.sort
+    end
+
+    def rails_routes(route_set = nil, base_url = "")
+      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?
+
+      flattened_routes = []
+
+      route_set.routes.each do |route|
+        # 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
+          flattened_routes.concat(rails_routes(route_app.routes, File.join(base_url, route.path.spec.to_s)))
+        else
+          route.base_url = base_url
+          flattened_routes << route
+        end
+      end
+
+      @_rails_routes = flattened_routes
+    end
+
+    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_by_controller_and_action[[controller.name.underscore.chomp('_controller'), method.to_s]] || []
+
+      Apipie.configuration.routes_formatter.format_routes(routes, args)
+    end
+
+    # create new method api description
+    def define_method_description(controller, method_name, dsl_data)
+      return if ignored?(controller, method_name)
+      ret_method_description = nil
+
+      versions = dsl_data[:api_versions] || []
+      versions = controller_versions(controller) if versions.empty?
+
+      versions.each do |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)
+        end
+
+        method_description = Apipie::MethodDescription.new(method_name, resource_description, dsl_data)
+
+        # we create separate method description for each version in
+        # case the method belongs to more versions. We return just one
+        # because the version doesn't matter for the purpose it's used
+        # (to wrap the original version with validators)
+        ret_method_description ||= method_description
+        resource_description.add_method_description(method_description)
+      end
+
+      ret_method_description
+    end
+
+    # create new resource api description
+    def define_resource_description(controller, version, dsl_data = nil)
+      return if ignored?(controller)
+
+      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_id, dsl_data, version)
+
+        Apipie.debug("@resource_descriptions[#{version}][#{resource_id}] = #{resource_description}")
+        @resource_descriptions[version][resource_id] ||= resource_description
+      end
+
+      return resource_description
+    end
+
+    # recursively searches what versions has the controller specified in
+    # resource_description? It's used to derivate the default value of
+    # versions for methods.
+    def controller_versions(controller)
+      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
+
+    def add_param_group(controller, name, &block)
+      key = "#{controller.name}##{name}"
+      @param_groups[key] = block
+    end
+
+    def get_param_group(controller, name)
+      key = "#{controller.name}##{name}"
+      if @param_groups.key?(key)
+        return @param_groups[key]
+      else
+        raise "param group #{key} not defined"
+      end
+    end
+
+    # get api for given method
+    #
+    # There are two ways how this method can be used:
+    # 1) Specify both parameters
+    #   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_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_id, method_name = nil)
+      if resource_id.is_a?(String)
+        crumbs = resource_id.split('#')
+        if method_name.nil?
+          method_name = crumbs.pop
+        end
+        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_id} does not exists.")
+      end
+      resource_description&.method_description(method_name.to_sym)
+    end
+    alias [] get_method_description
+
+    # options:
+    # => "users"
+    # => "v2#users"
+    # =>  V2::UsersController
+    def get_resource_description(resource, version = nil)
+      if resource.is_a?(String)
+        crumbs = resource.split('#')
+        if crumbs.size == 2
+          version = crumbs.first
+        end
+        version ||= Apipie.configuration.default_version
+        if @resource_descriptions.key?(version)
+          return @resource_descriptions[version][crumbs.last]
+        end
+      else
+        resource_id = get_resource_id(resource)
+        if version
+          resource_id = "#{version}##{resource_id}"
+        end
+
+        if resource_id.nil?
+          return nil
+        end
+        resource_description = get_resource_description(resource_id)
+        if resource_description && resource_description.controller.to_s == resource.to_s
+          return resource_description
+        end
+      end
+    end
+
+    # get all versions of resource description
+    def get_resource_descriptions(resource)
+      available_versions.map do |version|
+        get_resource_description(resource, version)
+      end.compact
+    end
+
+    # get all versions of method description
+    def get_method_descriptions(resource, method)
+      get_resource_descriptions(resource).map do |resource_description|
+        resource_description.method_description(method.to_sym)
+      end.compact
+    end
+
+    def remove_method_description(resource, versions, method_name)
+      versions.each do |version|
+        resource = get_resource_id(resource)
+        if resource_description = get_resource_description("#{version}##{resource}")
+          resource_description.remove_method_description(method_name)
+        end
+      end
+    end
+
+    # initialize variables for gathering dsl data
+    def init_env
+      @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] = [] }
+    end
+
+    def recorded_examples
+      return @recorded_examples if @recorded_examples
+      @recorded_examples = Apipie::Extractor::Writer.load_recorded_examples
+    end
+
+    def reload_examples
+      @recorded_examples = nil
+    end
+
+    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?
+
+      Apipie::SwaggerGenerator
+        .json_schema_for_method_response(method, return_code, allow_nulls)
+    end
+
+    delegate :json_schema_for_self_describing_class, to: :'Apipie::SwaggerGenerator'
+
+    def to_swagger_json(version, resource_id, method_name, language, clear_warnings = false)
+      return unless valid_search_args?(version, resource_id, method_name)
+
+      resources =
+        Apipie::Generator::Swagger::ResourceDescriptionsCollection
+          .new(resource_descriptions)
+          .filter(
+            resource_id: resource_id,
+            method_name: method_name,
+            version: version
+          )
+
+      Apipie::SwaggerGenerator.generate_from_resources(
+        resources,
+        version: version,
+        language: language,
+        clear_warnings: clear_warnings
+      )
+    end
+
+    def to_json(version, resource_id, method_name, lang)
+
+      return unless valid_search_args?(version, resource_id, method_name)
+
+      _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)|
+          result[k] = v.to_json(nil, lang) unless v._methods.blank?
+          result
+        end
+      else
+        [@resource_descriptions[version][resource_id].to_json(method_name, lang)]
+      end
+
+      url_args = Apipie.configuration.version_in_url ? version : ''
+
+      {
+        :docs => {
+          :name => Apipie.configuration.app_name,
+          :info => Apipie.app_info(version, lang),
+          :copyright => Apipie.configuration.copyright,
+          :doc_url => Apipie.full_url(url_args),
+          :api_url => Apipie.api_base_url(version),
+          :resources => _resources
+        }
+      }
+    end
+
+    def api_controllers_paths
+      Dir.glob(Apipie.configuration.api_controllers_matcher)
+    end
+
+    def reload_documentation
+      # don't load translated strings, we'll translate them later
+      old_locale = locale
+      locale = Apipie.configuration.default_locale
+
+      rails_mark_classes_for_reload
+
+      api_controllers_paths.each do |f|
+        load_controller_from_file f
+      end
+      @checksum = nil if Apipie.configuration.update_checksum
+
+      locale = old_locale
+    end
+
+    def load_documentation
+      if !@documentation_loaded || Apipie.configuration.reload_controllers?
+        Apipie.reload_documentation
+        @documentation_loaded = true
+      end
+    end
+
+    def compute_checksum
+      if Apipie.configuration.use_cache?
+        file_base = File.join(Apipie.configuration.cache_dir, Apipie.configuration.doc_base_url)
+        all_docs = {}
+        Dir.glob(file_base + '/*.json').sort.each do |f|
+          all_docs[File.basename(f, '.json')] = JSON.parse(File.read(f))
+        end
+      else
+        load_documentation if available_versions == []
+        all_docs = Apipie.available_versions.inject({}) do |all, version|
+          all.update(version => Apipie.to_json(version))
+        end
+      end
+      Digest::SHA1.hexdigest(JSON.dump(all_docs))
+    end
+
+    def checksum
+      @checksum ||= compute_checksum
+    end
+
+    # Is there a reason to interpret the DSL for this run?
+    # with specific setting for some environment there is no reason the dsl
+    # should be interpreted (e.g. no validations and doc from cache)
+    def active_dsl?
+      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.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
+
+        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
+      else
+        raise "Apipie: Can not resolve resource #{klass} name."
+      end
+    end
+
+    def locale
+      Apipie.configuration.locale&.call(nil)
+    end
+
+    def locale=(locale)
+      Apipie.configuration.locale&.call(locale)
+    end
+
+    def translate(str, locale)
+      if Apipie.configuration.translate
+        Apipie.configuration.translate.call(str, locale)
+      else
+        str
+      end
+    end
+
+    private
+
+    # 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_id]
+          return false unless resource_description.valid_method_name?(method_name)
+        end
+      end
+      return true
+    end
+
+    def version_prefix(klass)
+      version = controller_versions(klass).first
+      base_url = get_base_url(version)
+      return "/" if base_url.blank?
+      base_url[1..-1] + "/"
+    end
+
+    def get_base_url(version)
+      Apipie.configuration.api_base_url[version]
+    end
+
+    def get_resource_version(resource_description)
+      if resource_description.respond_to? :_version
+        resource_description._version
+      else
+        Apipie.configuration.default_version
+      end
+    end
+
+    def load_controller_from_file(controller_file)
+      require_dependency controller_file
+    end
+
+    def ignored?(controller, method = nil)
+      ignored = Apipie.configuration.ignored
+      return true if ignored.include?(controller.name)
+      return true if ignored.include?("#{controller.name}##{method}")
+    end
+
+    # Since Rails 3.2, the classes are reloaded only on file change.
+    # We need to reload all the controller classes to rebuild the
+    # docs, therefore we just force to reload all the code. This
+    # happens only when reload_controllers is set to true and only
+    # when showing the documentation.
+    #
+    # If cache_classes is set to false, it does nothing,
+    # as this would break loading of the controllers.
+    def rails_mark_classes_for_reload
+      unless Rails.application.config.cache_classes
+        clear_cached_routes!
+        Rails.application.reloader.reload!
+        init_env
+        reload_examples
+        Rails.application.reloader.prepare!
+      end
+    end
+
+  end
+end

data/lib/apipie/configuration.rb

@@ -0,0 +1,196 @@
+module Apipie
+  class Configuration
+    extend Forwardable
+
+    attr_accessor :app_name, :app_info, :copyright, :compress_examples,
+      :markup, :disqus_shortname,
+      :api_base_url, :doc_base_url, :required_by_default, :layout,
+      :default_version, :debug, :version_in_url, :namespaced_resources,
+      :validate, :validate_value, :validate_presence, :validate_key, :action_on_non_validated_keys, :authenticate, :doc_path,
+      :show_all_examples, :process_params, :update_checksum, :checksum_path,
+      :link_extension, :record, :languages, :translate, :locale, :default_locale,
+      :persist_show_in_doc, :authorize, :ignore_allow_blank_false
+
+    def_delegators :swagger, *Apipie::Generator::Swagger::Config.deprecated_methods
+
+    def swagger
+      Apipie::Generator::Swagger::Config.instance
+    end
+
+    def generator
+      Apipie::Generator::Config.instance
+    end
+
+    alias validate? validate
+    alias required_by_default? required_by_default
+    alias namespaced_resources? namespaced_resources
+
+    # 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.
+    attr_writer :reload_controllers
+
+    # specify routes if used router differ from default e.g.
+    #
+    # Api::Engine.routes
+    attr_accessor :api_routes
+
+    # a object responsible for transforming the routes loaded from Rails to a form
+    # to be used in the documentation, when using the `api!` keyword. By default,
+    # it's Apipie::RoutesFormatter. To customize the behaviour, one can inherit from
+    # from this class and override the methods as needed.
+    attr_accessor :routes_formatter
+
+    def reload_controllers?
+      @reload_controllers = Rails.env.development? unless defined? @reload_controllers
+
+      @reload_controllers && @api_controllers_matcher
+    end
+
+    def validate_value
+      validate? && @validate_value
+    end
+    alias validate_value? validate_value
+
+    def validate_presence
+      validate? && @validate_presence
+    end
+    alias validate_presence? validate_presence
+
+    def validate_key
+      validate? && @validate_key
+    end
+    alias validate_key? validate_key
+
+    def process_value?
+      @process_params
+    end
+    # set to true if you want to use pregenerated documentation cache and avoid
+    # generating the documentation on runtime (useful for production
+    # environment).
+    # You can generate the cache by running
+    #
+    #     rake apipie:cache
+    attr_accessor :use_cache
+    alias use_cache? use_cache
+
+    attr_writer :cache_dir
+    def cache_dir
+      @cache_dir ||= File.join(Rails.root, "public", "apipie-cache")
+    end
+
+    # if there is not obvious reason why the DSL should be turned on (no
+    # validations, cache turned on etc.), it's disabled to avoid unneeded
+    # allocation. It you need the DSL for other reasons, you can force the
+    # activation.
+    attr_writer :force_dsl
+    def force_dsl?
+      @force_dsl
+    end
+
+    # array of controller names (strings) (might include actions as well)
+    # to be ignored # when extracting description form calls.
+    # e.g. %w[Api::CommentsController Api::PostsController#post]
+    attr_writer :ignored_by_recorder
+    def ignored_by_recorder
+      @ignored_by_recorder ||= []
+      @ignored_by_recorder.map(&:to_s)
+    end
+
+    # array of controller names (strings) (might include actions as well)
+    # to be ignored # when generating the documentation
+    # e.g. %w[Api::CommentsController Api::PostsController#post]
+    attr_writer :ignored
+    def ignored
+      @ignored ||= []
+      @ignored.map(&:to_s)
+    end
+
+    # Persist the show_in_doc value in the examples if true. Use this if you
+    # cannot set the flag in the tests themselves (no rspec for example).
+    attr_writer :persist_show_in_doc
+
+    # comment to put before docs that was generated automatically. It's used to
+    # determine if the description should be overwritten next recording.
+    # If you want to keep the documentation (prevent from overriding), remove
+    # the line above the docs.
+    attr_writer :generated_doc_disclaimer
+    def generated_doc_disclaimer
+      @generated_doc_disclaimer ||= "# DOC GENERATED AUTOMATICALLY: REMOVE THIS LINE TO PREVENT REGENERATING NEXT TIME"
+    end
+
+    def use_disqus?
+      !@disqus_shortname.blank?
+    end
+
+    # set app description for default version
+    # to maintain backward compatibility
+    # new way: config.app_info[version] = description
+    def app_info=(description)
+      version = Apipie.configuration.default_version
+      @app_info[version] = description
+    end
+
+    # set base url for default version of API
+    # to set it for specific version use
+    # config.api_base_url[version] = url
+    def api_base_url=(url)
+      version = Apipie.configuration.default_version
+      @api_base_url[version] = url
+    end
+
+    def api_routes
+      @api_routes || Rails.application.routes
+    end
+
+    def initialize
+      @markup = Apipie::Markup::RDoc.new
+      @app_name = "Another API"
+      @app_info = ActiveSupport::HashWithIndifferentAccess.new
+      @copyright = nil
+      @validate = :implicitly
+      @validate_value = true
+      @validate_presence = true
+      @validate_key = false
+      @action_on_non_validated_keys = :raise
+      @required_by_default = false
+      @api_base_url = ActiveSupport::HashWithIndifferentAccess.new
+      @api_action_matcher = proc { |controller| controller.params[:action] }
+      @doc_base_url = "/apipie"
+      @layout = "apipie/apipie"
+      @disqus_shortname = nil
+      @default_version = "1.0"
+      @debug = false
+      @ignore_allow_blank_false = false
+      @version_in_url = true
+      @namespaced_resources = false
+      @doc_path = "doc"
+      @process_params = false
+      @checksum_path = [@doc_base_url, '/api/']
+      @update_checksum = false
+      @link_extension = ".html"
+      @record = false
+      @languages = []
+      @default_locale = 'en'
+      @locale = lambda { |locale| @default_locale }
+      @translate = lambda { |str, locale| str }
+      @persist_show_in_doc = false
+      @routes_formatter = RoutesFormatter.new
+    end
+  end
+end

data/lib/apipie/core_ext/route.rb

@@ -0,0 +1,9 @@
+module Apipie
+  module BaseUrlExtension
+    attr_accessor :base_url
+  end
+end
+
+class ActionDispatch::Journey::Route
+  include Apipie::BaseUrlExtension
+end