class ApipieDSL::Application

Attributes

class_descriptions[R]
refs[R]

Public Class Methods

new() click to toggle source
# File lib/apipie_dsl/application.rb, line 16
def initialize
  initialize_environment
end

Public Instance Methods

available_versions() click to toggle source
# File lib/apipie_dsl/application.rb, line 20
def available_versions
  @class_descriptions.keys.sort
end
class_versions(klass) click to toggle source
# File lib/apipie_dsl/application.rb, line 28
def class_versions(klass)
  ret = @class_versions[klass.to_s]
  return ret unless ret.empty?
  return [ApipieDSL.configuration.default_version] if [Class, Module].include?(klass) || klass.nil?

  class_versions(ApipieDSL.superclass_for(klass))
end
define_class_description(klass, version, dsl_data = {}) click to toggle source
# File lib/apipie_dsl/application.rb, line 97
def define_class_description(klass, version, dsl_data = {})
  return if ignored?(klass)

  class_name = dsl_data[:class_name] || get_class_name(klass)
  class_description = @class_descriptions[version][class_name]
  if class_description
    # Already defined the class somewhere (probably in
    # some method. Updating just meta data from dsl
    class_description.update_from_dsl_data(dsl_data) unless dsl_data.empty?
  else
    class_description = ApipieDSL::ClassDescription.new(klass, class_name, dsl_data, version)
    ApipieDSL.debug("@class_descriptions[#{version}][#{class_name}] = #{class_description}")
    @class_descriptions[version][class_description.id] ||= class_description
  end
  class_description.refs.each do |ref|
    if @refs[version][ref]
      ApipieDSL.debug("Overwriting refs for #{class_name}")
    end

    @refs[version][ref] = class_description
  end
  class_description
end
define_method_description(klass, method_name, dsl_data) click to toggle source
# File lib/apipie_dsl/application.rb, line 68
def define_method_description(klass, method_name, dsl_data)
  return if ignored?(klass, method_name)

  ret_method_description = nil
  versions = dsl_data[:dsl_versions] || []
  versions = class_versions(klass) if versions.empty?

  versions.each do |version|
    class_name_with_version = "#{version}##{get_class_name(klass)}"
    class_description = get_class_description(class_name_with_version)

    if class_description.nil?
      class_dsl_data = { sections: [ApipieDSL.configuration.default_section] }
      class_description = define_class_description(klass, version, class_dsl_data)
    end

    method_description = ApipieDSL::MethodDescription.new(method_name, class_description, dsl_data)

    # Create separate method description for each version in
    # case the method belongs to more versions. 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
    class_description.add_method_description(method_description)
  end

  ret_method_description
end
define_param_group(klass, name, &block) click to toggle source
# File lib/apipie_dsl/application.rb, line 44
def define_param_group(klass, name, &block)
  key = "#{klass.name}##{name}"
  @param_groups[key] = block
end
define_prop_group(klass, name, &block) click to toggle source
# File lib/apipie_dsl/application.rb, line 56
def define_prop_group(klass, name, &block)
  key = "#{klass.name}##{name}"
  @prop_groups[key] = block
end
docs(version, class_name, method_name, lang, section = nil) click to toggle source
# File lib/apipie_dsl/application.rb, line 191
def docs(version, class_name, method_name, lang, section = nil)
  empty_doc = empty_docs(version, lang)
  return empty_doc unless valid_search_args?(version, class_name, method_name)

  classes =
    if class_name.nil?
      class_descriptions[version].each_with_object({}) do |(name, description), result|
        result[name] = description.docs(section, nil, lang)
        result
      end
    else
      [@class_descriptions[version][class_name].docs(section, method_name, lang)]
    end
  empty_doc[:docs][:classes] = classes
  empty_doc
end
dsl_classes_paths() click to toggle source
# File lib/apipie_dsl/application.rb, line 208
def dsl_classes_paths
  ApipieDSL.configuration.dsl_classes_matchers.map { |m| Dir.glob(m) }
           .concat(Dir.glob(ApipieDSL.configuration.dsl_classes_matcher))
           .flatten.uniq
end
get_class_description(klass, version = nil) click to toggle source

options:

> “io”

> “v2#io”

> V2::IO

# File lib/apipie_dsl/application.rb, line 150
def get_class_description(klass, version = nil)
  return nil if [NilClass, nil].include?(klass)

  if klass.is_a?(String)
    crumbs = klass.split('#')
    version = crumbs.first if crumbs.size == 2
    version ||= ApipieDSL.configuration.default_version
    return @class_descriptions[version][crumbs.last] if @class_descriptions.key?(version)
  else
    class_name = get_class_name(klass)
    class_name = "#{version}##{class_name}" if version
    return nil if class_name.nil?

    class_description = get_class_description(class_name)
    return class_description if class_description && class_description.klass.to_s == klass.to_s
  end
end
get_class_descriptions(klass) click to toggle source

get all versions of class description

# File lib/apipie_dsl/application.rb, line 169
def get_class_descriptions(klass)
  available_versions.map do |version|
    get_class_description(klass, version)
  end.compact
end
get_class_name(klass) click to toggle source
# File lib/apipie_dsl/application.rb, line 36
def get_class_name(klass)
  class_name = klass.respond_to?(:name) ? klass.name : klass
  raise ArgumentError, "ApipieDSL: Can not resolve class #{klass} name." unless class_name.is_a?(String)
  return class_name if ApipieDSL.configuration.class_full_names?

  class_name.split('::').last
end
get_method_description(class_name, method_name = nil) click to toggle source

get method

There are two ways how this method can be used: 1) Specify both parameters

class_name:
    class - IO
    string with resource name and version - "v1#io"
method_name: name of the method (string or symbol)

2) Specify only first parameter:

class_name: string containing both class and method name joined
with '#' symbol.
- "io#puts" get default version
- "v2#io#puts" get specific version
# File lib/apipie_dsl/application.rb, line 135
def get_method_description(class_name, method_name = nil)
  ApipieDSL.debug("Getting #{class_name}##{method_name} documentation")
  crumbs = class_name.split('#')
  method_name = crumbs.pop if method_name.nil?
  class_name = crumbs.join('#')
  class_description = get_class_description(class_name)
  raise ArgumentError, "Class #{class_name} does not exists." if class_description.nil?

  class_description.method_description(method_name.to_sym)
end
get_method_descriptions(klass, method) click to toggle source

get all versions of method description

# File lib/apipie_dsl/application.rb, line 176
def get_method_descriptions(klass, method)
  get_class_descriptions(klass).map do |class_description|
    class_description.method_description(method.to_sym)
  end.compact
end
get_param_group(klass, name) click to toggle source
# File lib/apipie_dsl/application.rb, line 49
def get_param_group(klass, name)
  key = "#{klass.name}##{name}"
  raise StandardError, "Param group #{key} is not defined" unless @param_groups.key?(key)

  @param_groups[key]
end
get_prop_group(klass, name) click to toggle source
# File lib/apipie_dsl/application.rb, line 61
def get_prop_group(klass, name)
  key = "#{klass.name}##{name}"
  raise StandardError, "Prop group #{key} is not defined" unless @prop_groups.key?(key)

  @prop_groups[key]
end
ignored?(klass, method = nil) click to toggle source
# File lib/apipie_dsl/application.rb, line 222
def ignored?(klass, method = nil)
  ignored = ApipieDSL.configuration.ignored
  class_name = get_class_name(klass.name)
  return true if ignored.include?(class_name)
  return true if ignored.include?("#{class_name}##{method}")
end
load_documentation() click to toggle source
# File lib/apipie_dsl/application.rb, line 254
def load_documentation
  return if @documentation_loaded && !ApipieDSL.configuration.reload_dsl?

  ApipieDSL.reload_documentation
  @documentation_loaded = true
end
locale() click to toggle source
# File lib/apipie_dsl/application.rb, line 261
def locale
  ApipieDSL.configuration.locale.call(nil) if ApipieDSL.configuration.locale
end
reload_documentation() click to toggle source
# File lib/apipie_dsl/application.rb, line 229
def reload_documentation
  # don't load translated strings, we'll translate them later
  old_locale = locale
  reset_locale(ApipieDSL.configuration.default_locale)

  rails_mark_classes_for_reload if ApipieDSL.configuration.rails?

  dsl_classes_paths.each do |file|
    begin
      ApipieDSL.debug("Loading #{file}")
      if ApipieDSL.configuration.rails?
        load_class_from_file(file)
      else
        load(file)
      end
    rescue StandardError
      # Some constant the file uses may not be defined
      # before it's loaded
      # TODO: better loading
    end
  end

  reset_locale(old_locale)
end
remove_method_description(klass, versions, method_name) click to toggle source
# File lib/apipie_dsl/application.rb, line 182
def remove_method_description(klass, versions, method_name)
  versions.each do |version|
    klass = get_class_name(klass)
    if (class_description = class_description("#{version}##{klass}"))
      class_description.remove_method_description(method_name)
    end
  end
end
reset_locale(loc) click to toggle source
# File lib/apipie_dsl/application.rb, line 265
def reset_locale(loc)
  ApipieDSL.configuration.locale.call(loc) if ApipieDSL.configuration.locale
end
set_class_versions(klass, versions) click to toggle source
# File lib/apipie_dsl/application.rb, line 24
def set_class_versions(klass, versions)
  @class_versions[klass.to_s] = versions
end
translate(str, locale) click to toggle source
# File lib/apipie_dsl/application.rb, line 214
def translate(str, locale)
  if ApipieDSL.configuration.translate
    ApipieDSL.configuration.translate.call(str, locale)
  else
    str
  end
end

Private Instance Methods

empty_docs(version, lang) click to toggle source
# File lib/apipie_dsl/application.rb, line 279
def empty_docs(version, lang)
  url_args = ApipieDSL.configuration.version_in_url ? version : ''
  {
    docs: {
      name: ApipieDSL.configuration.app_name,
      info: ApipieDSL.app_info(version, lang),
      copyright: ApipieDSL.configuration.copyright,
      doc_url: ApipieDSL.full_url(url_args),
      classes: {}
    }
  }
end
initialize_environment() click to toggle source
# File lib/apipie_dsl/application.rb, line 271
def initialize_environment
  @class_descriptions ||= Hash.new { |h, version| h[version] = {} }
  @class_versions ||= Hash.new { |h, klass| h[klass.to_s] = [] }
  @refs ||= Hash.new { |h, version| h[version] = {} }
  @param_groups ||= {}
  @prop_groups ||= {}
end
load_class_from_file(class_file) click to toggle source
# File lib/apipie_dsl/application.rb, line 292
def load_class_from_file(class_file)
  require_dependency class_file
end
rails_mark_classes_for_reload() click to toggle source

Since Rails 3.2, the classes are reloaded only on file change. We need to reload all the classes to rebuild the docs, therefore we just force to reload all the code.

# File lib/apipie_dsl/application.rb, line 299
def rails_mark_classes_for_reload
  unless Rails.application.config.cache_classes
    Rails::VERSION::MAJOR == 4 ? ActionDispatch::Reloader.cleanup! : Rails.application.reloader.reload!
    initialize_environment
    Rails::VERSION::MAJOR == 4 ? ActionDispatch::Reloader.prepare! : Rails.application.reloader.prepare!
  end
end
valid_search_args?(version, class_name, method_name) click to toggle source
# File lib/apipie_dsl/application.rb, line 307
def valid_search_args?(version, class_name, method_name)
  return false unless class_descriptions.key?(version)

  if class_name
    return false unless class_descriptions[version].key?(class_name)

    if method_name
      class_description = class_descriptions[version][class_name]
      return false unless class_description.valid_method_name?(method_name)
    end
  end
  true
end