rails_api_documentation 0.1.0

data/app/views/shared/_response_table.slim

@@ -0,0 +1,14 @@
+div.flex-table
+  div.flex-line.row
+    / Угловой елемент
+    div.flex-item Parameter
+    div.flex-item Value
+  - locals[:rows].each do |row_name, node|
+    div.flex-line.row
+      div.flex-item  #{row_name}
+      - if node.nested?
+        div.flex-item.next-is-nested #{node.attr}(Nested)
+      - else
+        div.flex-item #{node.attr}
+    - if node.nested?
+      = render 'shared/response_table', locals: { rows: node.nested }

data/app/views/shared/_table.slim

@@ -0,0 +1,20 @@
+- nesting = locals[:nesting].to_a.push(locals[:model])
+
+div.flex-table
+  div.flex-line.row
+    / Угловой елемент
+    div.flex-item Parameter
+    div.flex-item Type
+    - @request_headers.each_value do |header|
+      div.flex-item = header
+  - locals[:rows].each do |row_name, row_values|
+    div.flex-line.row
+      div.flex-item  #{row_name} #{'*' if row_values.required?}
+      - if row_values.nested?
+        div.flex-item.next-is-nested #{row_values[:model]}(Nested)
+      - else
+        div.flex-item #{row_values[:type]}
+      - @request_headers.each_key do |header_alias|
+        div.flex-item = row_values[header_alias]
+    - if row_values.nested?
+      = render 'shared/table', locals: { nesting: nesting, model: row_values[:model] || row_name, rows: row_values[:nested] }

data/config/routes.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+# Match IDs with dots in them
+# id_pattern = /[^\/]+/
+
+RailsApiDoc::Engine.routes.draw do
+  resource :api_doc
+
+  root to: 'api_docs#index'
+end

data/lib/rails_api_doc/config/validator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+class RailsApiDoc::Config::Validator
+
+  cattr_accessor :checkers
+  self.checkers = []
+
+  def self.valid_param?(controller_param, api_param_data)
+    checkers.all? do |checker|
+      checker.valid?(controller_param, api_param_data)
+    end
+  end
+
+end

data/lib/rails_api_doc/configuration.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+# :nodoc:
+class RailsApiDoc::Configuration
+
+  def initialize
+  end
+
+end

data/lib/rails_api_doc/controller/attribute_parser.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+# :nodoc:
+class RailsApiDoc::Controller::AttributeParser
+
+  # TODO : Change to I18n. Added on: 08.10.16. Added by: <@vshaveyko>
+  WRONG_NAME_ERROR_STRING = 'Name should consist only of letters\ciphers\underscores'
+
+  class << self
+
+    def parse_attributes(params)
+      type = :enum if params[:enum].present?
+
+      {
+        name: parse_name(params[:name]),
+        type: type || parse_type(params[:type]),
+        enum: parse_enum(params[:enum])
+      }.compact
+    end
+
+    private
+
+    def parse_name(name_string)
+      return if name_string.blank?
+      raise ArgumentError, WRONG_NAME_ERROR_STRING unless name_string =~ /[A-z0-9_]*/
+      name_string.underscore.to_sym
+    end
+
+    def parse_enum(enum_string)
+      return if enum_string.blank?
+      enum_string.split(',').map do |enum_value|
+        parse_enum_value(enum_value)
+      end
+    end
+
+    def parse_enum_value(value)
+      case value
+      when /^\d+$/
+        value.to_i
+      when 'true'
+        true
+      when 'false'
+        false
+      else
+        value
+      end
+    end
+
+    def parse_type(type)
+      return if type.blank?
+      type.constantize
+    end
+
+  end
+
+end

data/lib/rails_api_doc/controller/parameter/repository/param.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+class RailsApiDoc::Controller::Parameter::Repository::Param
+
+  ACCEPTED_TYPES = [String, Integer, Object, Array, DateTime, :enum, :model].freeze
+
+  # @type - type to check
+  def self.accepted_nested_type?(type)
+    type == Object || type == :model
+  end
+
+  def self.valid_type?(type)
+    return if type.in?(ACCEPTED_TYPES)
+    raise ArgumentError, "Wrong type: #{type}. " \
+                         "Correct types are: #{ACCEPTED_TYPES}."
+  end
+
+  def self.valid_enum?(enum)
+    return if enum.nil? || enum.is_a?(Array)
+    raise ArgumentError, 'Enum must be an array.'
+  end
+
+  def self.valid_nested?(type, block_given)
+    return false unless accepted_nested_type?(type)
+    return true if block_given
+    raise ArgumentError, 'Empty object passed.'
+  end
+
+  def initialize(name, store)
+    @name = name
+    @store = store
+  end
+
+  def nested?
+    self.class.accepted_nested_type?(@store[:type])
+  end
+
+  def required?
+    @store[:required]
+  end
+
+  def method_missing(name, *args)
+    return @store.send(name, *args) if respond_to_missing?(name)
+    super
+  end
+
+  def respond_to_missing?(name)
+    @store.respond_to?(name)
+  end
+
+end

data/lib/rails_api_doc/controller/parameter/repository.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+# :nodoc:
+class RailsApiDoc::Controller::Parameter::Repository
+
+  @repo = Hash.new { |hsh, key| hsh[key] = Hash.new { |hsh, key| hsh[key] = Param.new(key) } }
+
+  class << self
+
+    def method_missing(name, *args, &block)
+      return @repo.send(name, *args, &block) if respond_to_missing?(name)
+      super
+    end
+
+    def registered_controllers
+      @repo.keys
+    end
+
+    def respond_to_missing?(method, *)
+      @repo.respond_to?(method)
+    end
+
+    def []=(key, value)
+      unless key < ActionController::Base
+        raise ArgumentError, 'Repository keys are controllers only'
+      end
+
+      super
+    end
+
+  end
+
+end

data/lib/rails_api_doc/controller/parameter.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+module RailsApiDoc::Controller::Parameter
+
+  VALID_KEYS = [:type, :required, :enum, :model].freeze #:nodoc:
+
+  # Use parameter in controller to defined REQUEST parameter.
+  # Adds it to repository: RailsApiDoc::Controller::Parameter::Repository
+  def parameter(name, options, &block)
+    raise ArgumentError, 'Parameter already defined.' if repo.key?(name)
+
+    validate_options(options, block_given?)
+
+    define_parameter(name, options, &block)
+  end
+
+  private
+
+  def validate_options(options, block_given)
+    if options.nil? || options.empty?
+      raise ArgumentError, 'Empty options passed.'
+    end
+
+    options.assert_valid_keys(VALID_KEYS)
+
+    Repository::Param.valid_type?(options[:type])
+
+    Repository::Param.valid_enum?(options[:enum])
+
+    Repository::Param.valid_nested?(options[:type], block_given)
+  end
+
+  # default repo can be reassigned to deal with nested parameters
+  # see nested_parameter
+  def repo
+    @repo || Repository[self]
+  end
+
+  def define_parameter(name, parameter_data, &block)
+    repo[name] = \
+      if Repository::Param.valid_nested?(parameter_data[:type], block_given?)
+        Repository::Param.new(name, nested_parameter(parameter_data, &block))
+      else
+        Repository::Param.new(name, parameter_data)
+      end
+  end
+
+  def nested_parameter(parameter_data)
+    _backup_repo = @repo
+    @repo = {}
+    yield
+    parameter_data.merge(nested: @repo)
+  ensure
+    @repo = _backup_repo
+  end
+
+end

data/lib/rails_api_doc/controller/response/rabl.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+# :nodoc:
+# :nodoc:
+class RailsApiDoc::Controller::Response
+
+  # :nodoc:
+  class Rabl
+
+    class << self
+
+      attr_accessor :renderer
+
+    end
+
+    attr_reader :map
+
+    # pass all controllers registered for api doc
+    # TODO: add setting for displaying all from start
+    def initialize(controllers)
+      @controllers = controllers
+      @routes = Rails.application.routes.set.anchored_routes.reject { |r| r.defaults[:internal] }
+      @map = construct_controller_template_map
+    end
+
+    def load_template(ctrl, action)
+      RablCompiler.new("#{ctrl.controller_path}/#{action}").compile_source
+    end
+
+    def action_route(ctrl, action)
+      action_route = @map[ctrl][:routes].detect { |r| r.defaults[:action] == action }
+      method = action_route.instance_variable_get(:@request_method_match).first.name.split('::').last
+      route = action_route.path.spec.to_s
+      [method, route].join(' ')
+    end
+
+    private
+
+    def construct_controller_template_map
+      @controllers.each_with_object({}) do |ctrl, map|
+        map[ctrl] = ctrl_actions(ctrl)
+      end
+    end
+
+    def ctrl_actions(ctrl)
+      routes = @routes.select do |route|
+        route.defaults[:controller].in?([ctrl.controller_path, ctrl.controller_name])
+      end
+      actions = routes.map { |r| r.defaults[:action] }
+      {
+        routes: routes,
+        actions: ctrl.action_methods
+      }
+    end
+
+  end
+
+end

data/lib/rails_api_doc/controller/response/rabl_compiler.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+# :nodoc:
+# :nodoc:
+class RailsApiDoc::Controller::Response
+
+  class Node < Struct.new(:name, :attr, :nested)
+
+    def nested?
+      !nested.nil?
+    end
+
+  end
+
+  # template struct
+  class CompiledAttributes
+
+    attr_accessor :nodes, :data, :root_name
+
+    def initialize
+      @nodes = {}
+      # @cache_key = false
+    end
+
+    def each(&block)
+      @nodes.each &block
+    end
+
+    # def initialize_dup(other)
+    # super
+    # self.nodes = other.nodes.dup
+    # end
+
+    def add(n)
+      if n[:attr] && n[:name] != n[:attr]
+        n[:name] = "#{n[:name]}(#{n[:attr]})"
+      end
+
+      @nodes[n[:name]] = Node.new(n[:name], n[:attr], n[:nested])
+    end
+
+    def extends(template)
+      @nodes.merge! template.nodes
+    end
+
+  end
+  # Class that will compile RABL source code into a hash
+  # representing data structure
+  class RablCompiler
+
+    def initialize(file_path, view_path: 'app/views')
+      paths = Dir["#{view_path}/#{file_path}{.json,}.rabl"]
+      file_path = paths.find { |path| File.exist?(path) }
+
+      @source = _preserve_ivars File.read(file_path)
+    rescue
+    end
+
+    # find all instance variables used and prepend them with ':' to
+    # turn into symbols on compile. otherwise they turn to nil(random ivar is nil)
+    def _preserve_ivars(source)
+      source.gsub /(@[^\s]*)/, ':\1'
+    end
+
+    # Compile from source code and return the CompiledAttributes created.
+    def compile_source
+      return unless @source
+      @attributes = CompiledAttributes.new
+      instance_eval(@source)
+      @attributes
+    end
+
+    #
+    # Sets the object to be used as the data for the template
+    # Example:
+    #   object :@user
+    #   object :@user, :root => :author
+    #
+    # dont care about object / collection options. need only attributes
+    def object(a)
+      @attributes.data = a
+    end
+    alias collection object
+
+    #
+    # Includes the attribute or method in the output
+    # Example:
+    #   attributes :id, :name
+    #   attribute :email => :super_secret
+    #
+    # save attribute to nodes
+    def attribute(*args)
+      if args.first.is_a?(Hash)
+        args.first.each_pair do |key, name|
+          @attributes.add(name: name, attr: key)
+        end
+      else
+        options = args.extract_options!
+        args.each do |name|
+          key = options[:as] || name
+          @attributes.add(name: name, attr: key)
+        end
+      end
+    end
+    alias attributes attribute
+
+    #
+    # Creates a child node to be included in the output.
+    # name_or data can be an object or collection or a method to call on the data. It
+    # accepts :root and :partial options.
+    # Notes that partial and blocks are not compatible
+    # Example:
+    #   child(:@posts, :root => :posts) { attribute :id }
+    #   child(:posts, :partial => 'posts/base')
+    #   child(:@posts => :cool_posts, :root => :posts) { attribute :id }
+    #
+    def child(name_or_data, options = {})
+      data, name = extract_data_and_name(name_or_data)
+
+      if options.empty? && new_options = name_or_data.to_a.second
+        options = [new_options].to_h
+      end
+
+      name = options[:root] if options.key? :root
+
+      if options.key?(:partial)
+        attrs = RablCompiler.new(options[:partial]).compile_source
+      elsif block_given?
+        attrs = sub_compile(data) { yield }
+      end
+
+      @attributes.add(name: name, attr: data, nested: attrs.nodes)
+    end
+
+    #
+    # Glues data from a child node to the output
+    # Example:
+    #   glue(:@user) { attribute :name }
+    #
+    def glue(data)
+      return unless block_given?
+
+      template = sub_compile(data) { yield }
+
+      template.nodes.each_value do |value|
+        @attributes.add name: value.name, attr: "#{data}.#{value.attr}", nested: value.nested
+      end
+    end
+
+    #
+    # Creates an arbitrary node in the json output.
+    # It accepts :if option to create conditionnal nodes. The current data will
+    # be passed to the block so it is advised to use it instead of ivars.
+    # Example:
+    #   node(:name) { |user| user.first_name + user.last_name }
+    #   node(:role, if: ->(u) { !u.admin? }) { |u| u.role }
+    #
+    def node(name = nil, _options = {})
+      return unless block_given?
+      @attributes.add name: name
+    end
+    alias code node
+
+    #
+    # Merge arbitrary data into json output. Given block should
+    # return a hash.
+    # Example:
+    #   merge { |item| partial("specific/#{item.to_s}", object: item) }
+    #
+    # def merge
+      # return unless block_given?
+      # yield
+    # end
+
+    #
+    # Extends an existing rabl template
+    # Example:
+    #   extends 'users/base'
+    #
+    def extends(path)
+      extended = RablCompiler.new(path).compile_source
+      @attributes.extends extended
+    end
+
+    #
+    # Provide a conditionnal block
+    #
+    # condition(->(u) { u.is_a?(Admin) }) do
+    #   attributes :secret
+    # end
+    #
+    # def condition(*)
+      # return unless block_given?
+      # template = sub_compile(nil, true) { yield }
+      # @attributes.extends template
+    # end
+    #
+    def method_missing(name, *attrs)
+      return p("#{name} is not implemented in railsApiDoc") if name.in?(['merge', 'condtiion'])
+      super
+    end
+
+    protected
+
+    #
+    # Extract data root_name and root name
+    # Example:
+    #   :@users -> [:@users, nil]
+    #   :@users => :authors -> [:@users, :authors]
+    #
+    def extract_data_and_name(name_or_data)
+      case name_or_data
+      when Symbol
+        str = name_or_data.to_s
+        str.start_with?('@') ? [name_or_data, str[1..-1]] : [name_or_data, name_or_data]
+      when Hash
+        name_or_data.first
+      else
+        name_or_data
+      end
+    end
+
+    def sub_compile(data, only_nodes = false)
+      raise unless block_given?
+      old_template = @attributes
+      @attributes = CompiledAttributes.new
+      yield
+      @attributes.data = data
+      only_nodes ? @attributes.nodes : @attributes
+    ensure
+      @attributes = old_template
+    end
+
+  end
+
+end