rails_api_documentation 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4c67c2cdc12a310b1972630df13fa2a7dbab76e5
-  data.tar.gz: cd2a6c178374ad1a8e9e9870fca0efe7f00c0796
+  metadata.gz: 2eafaedd7e6a3665cb3f17763d5204a80ec35e84
+  data.tar.gz: 3b09eb7ddd55e8300a60a0a4514084c8b03a2496
 SHA512:
-  metadata.gz: 00397485504bad53e5ea83f3414165d59a9328375461cfb78355d650ced0e2615be6f7aaf4a4691686a059885f8eacb3e16642f36e00f2473139364675a391b8
-  data.tar.gz: e533be586b8eb26d39ce266ecccb45d37e911e20afda1f8d6eaf058d6108bc50ae48398d238611bf2fa8440879c71aaea7ebacd4b5225b2b489ebd1c707232c1
+  metadata.gz: 8aff4ed365764127675f1150047a0ef21f05da820834a77a5459607bb0c7319b60123643f24398cd9003bda449a304ce8de2b094420a51409d321c347970ef17
+  data.tar.gz: 4d095bb8a1ea783f09820189c7c96544d21e1adf57b6d8a8065b24701fdef752e7cc9461cc755aec682c6fe7849cf29621157580fde4a39c86e149208c5590e6

data/Gemfile

@@ -21,6 +21,7 @@ gem 'therubyrhino', '2.0.4',        platforms: :jruby
 
 gem 'pry'
 gem 'pry-stack_explorer'
+gem 'pry-rescue'
 
 group :development, :test do
   gem 'rspec-rails', '~> 3.5'

data/README.md

@@ -17,6 +17,13 @@ Or install it yourself as:
 
     $ gem install rails_api_doc
 
+## Features
+
++ displaying application api if used in one of correct ways
+  ![alt tag](https://raw.githubusercontent.com/vshaveyko/rails_api_doc/master/preview.png)
++ Integration with Rabl if it is bundled
++ ```resource_params``` method that will filter incoming params for you
+
 ## Usage
 
 To display api documentation on route '/api_doc' you need to:
@@ -49,12 +56,89 @@ To display api documentation on route '/api_doc' you need to:
     end
   ```
 
-Parameter type may be one of these:
+## Strong params
+
+  You may want to use your defined request api to filter incoming parameters.
+  Usually we use something like `params.permit(:name, :age)`, but no more!
+  With this gem bundled you can do this:
 
   ```ruby
-    ACCEPTED_TYPES = [Bool, String, Integer, Object, Array, DateTime, :enum, :model].freeze
+
+    parameter :body, type: :string
+    parameter :title, type: :string
+
+    # controller action
+    def create
+      Comment.create!(resource_params)
+    end
+
+  ```
+
+  and if request is `POST '/comments', params: { body: 'Comment body', title: 'Comment title', age: 34 }`
+
+  Comment will be created with: `Comment(body='Comment body', title='Comment title', age=nil)`
+
+## Types
+
+  Parameter type may be one of these:
+
+  ```ruby
+
+   # Non nested
+    :bool - Boolean type, accepts true, false, 'true', 'false'
+    :string - will accept anything beside nested type
+    :integer - accepts numbers as string value, and usual numbers
+    :array - array of atomic values (integer, strings, etc)
+    :datetime - string with some datetime representation accepted by DateTime.parse
+    :enum - one of predefined values of enum: option (only atomic types)
+
+   # nested
+    :object - usual nested type. comes very handy with rails nested_attributes feature
+    :ary_object - array of :object type, rails nested_attributes on has_many
+
   ```
 
+## TODO's
++ type for id reference with model field to display associated model and CONTROLLER in params for linking
+
++ native DSL for defining response
+```ruby
+  action :show do
+    response :age, type: Integer
+    response :name, type String
+    response :data, type: :model, model: Datum do
+      response :creation_date, type: DateTime
+      response :comment, type: String
+    end
+  end
+```
++ native DSL for defining scopes
+```ruby
+scope :age, desc: 'Filters authors by given age'
+```
++ dsl for extending response parameters
+```ruby
+  response :data, type: :model, model: Datum do
+    extends DataController, action: :show
+  end
+```
++ dsl for extending request parameters
+```ruby
+parameter :data, type: :model, model: Datum do
+  extends DataController, action: :show
+end
+```
++ ability to split request params to actions(low prior)
++ CRUD for all parameters
++ merging parameters from all sources before display
++ pull everything that's possible to config
+
+## Development
+
++ add specs for everything done
++ inline documentation
++ README FAQ on added functionality with examples
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/rails_api_doc/config/validate_ary_object.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+class RailsApiDoc::Config::ValidateAryObject
+
+  #
+  # @api_param_data - RailsApiDoc::Controller::Parameter::Repository::Param
+  # @controller_param - ActionController::Parameter
+  #
+  # check validation of current type by given data
+  #
+  # ary_object: check that parameter is array of parameters
+  #
+  def valid?(controller_param, api_param_data)
+    return true unless api_param_data.ary_object?
+
+    controller_param.is_a?(Array) && begin
+      controller_param.all? { |param| param.is_a?(::ActionController::Parameters) }
+    end
+  end
+
+end

data/lib/rails_api_doc/config/validate_enum.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+# :nodoc:
+class RailsApiDoc::Config::ValidateEnum
+
+  #
+  # @api_param_data - RailsApiDoc::Controller::Parameter::Repository::Param
+  # @controller_param - ActionController::Parameter
+  #
+  # check validation of current type by given data
+  #
+  # enum: check that enum array includes given value
+  #
+  def valid?(controller_param, api_param_data)
+    return true unless api_param_data.enum?
+
+    api_param_data[:enum].include?(controller_param)
+  end
+
+end

data/lib/rails_api_doc/config/validate_type.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+# :nodoc:
+class RailsApiDoc::Config::ValidateType
+
+  #
+  # @api_param_data - RailsApiDoc::Controller::Parameter::Repository::Param
+  # @controller_param - ActionController::Parameter
+  #
+  # check validation of current type by given data
+  #
+  # type: check that param value is of requested type
+  # Examples:
+  #
+  #   1. controller_param == '1'                                                , api_param_data[:type] == :integer                                  > ok
+  #   2. controller_param == 'string'                                           , api_param_data[:type] == :integer                                  > not_ok
+  #   3. controller_param == {a: 'b'}                                           , api_param_data[:type] == :object                                   > ok
+  #   4. controller_param == [{a:'b'}, {c: 'd'}]                                , api_param_data[:type] == :ary_object                               > ok
+  #   5. controller_param == "2016-11-26 13:55:30 +0200"(or any other singature , use DateTime.parse to check) , api_param_data[:type] == :datetime  > ok
+  #   6. controller_param == 'true'                                             , api_param_data[:type] == :bool                                     > ok
+  #   7. controller_param == true                                               , api_param_data[:type] == :bool                                     > ok
+  #   8. controller_param == 'ok'                                               , api_param_data[:type] == :bool                                     > not_ok
+  #   9. controller_param == ['1', '2', 3]                                      , api_param_data[:type] == :array                                    > ok
+  #  10. controller_param == [{a:'b'}]                                          , api_param_data[:type] == :array                                    > not_ok
+  #
+  # TODO: write rspec for this cases and implement
+  def valid?(_controller_param, _api_param_data)
+    true
+  end
+
+end

data/lib/rails_api_doc/config/validator.rb

@@ -1,14 +1,33 @@
 # frozen_string_literal: true
 # author: Vadim Shaveiko <@vshaveyko>
+require_relative 'validate_ary_object'
+require_relative 'validate_enum'
+require_relative 'validate_type'
+
 class RailsApiDoc::Config::Validator
 
-  cattr_accessor :checkers
-  self.checkers = []
+  class << self
+
+    attr_accessor :checkers
+
+    def add_checker(klass)
+      return if checkers.detect { |c| c.is_a?(klass) }
+
+      checkers << klass.new
+    end
 
-  def self.valid_param?(controller_param, api_param_data)
-    checkers.all? do |checker|
-      checker.valid?(controller_param, api_param_data)
+    def remove_checker(klass)
+      checkers.delete_if { |c| c.is_a?(klass) }
     end
+
+    def valid_param?(controller_param, api_param_data)
+      checkers.all? do |checker|
+        checker.valid?(controller_param, api_param_data)
+      end
+    end
+
   end
 
+  self.checkers = [RailsApiDoc::Config::ValidateEnum.new, RailsApiDoc::Config::ValidateAryObject.new]
+
 end

data/lib/rails_api_doc/config.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+# :nodoc:
+class RailsApiDoc::Config
+
+  attr_accessor :check_params_type
+
+  def check_params_type=(value)
+    if value
+      Validator.add_checker(ValidateType)
+    else
+      Validator.remove_checker(ValidateType)
+    end
+  end
+
+end
+
+require_relative 'config/validator'

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

@@ -2,21 +2,26 @@
 # author: Vadim Shaveiko <@vshaveyko>
 class RailsApiDoc::Controller::Parameter::Repository::Param
 
-  ACCEPTED_TYPES = [::Bool, String, Integer, Object, Array, DateTime, :enum, :model].freeze
+  NESTED_TYPES = [:ary_object, :object, :model, Object].freeze
+
+  STRAIGHT_TYPES = [:bool, :string, :integer, :array, :datetime, :enum, String, Object, Integer, Array, DateTime].freeze
+
+  ACCEPTED_TYPES = (NESTED_TYPES + STRAIGHT_TYPES).freeze
 
   # @type - type to check
   def self.accepted_nested_type?(type)
-    type == Object || type == :model
+    type.in?(NESTED_TYPES)
   end
 
   def self.valid_type?(type)
-    return if type.in?(ACCEPTED_TYPES)
+    return if type.nil? || 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)
+  def self.valid_enum?(type, enum)
+    return false unless type == :enum
+    return if enum.is_a?(Array)
     raise ArgumentError, 'Enum must be an array.'
   end
 
@@ -31,16 +36,28 @@ class RailsApiDoc::Controller::Parameter::Repository::Param
     @store = store
   end
 
+  def enum?
+    @store[:type] == :enum && @store[:enum].present?
+  end
+
+  def ary_object?
+    @store[:type] == :ary_object
+  end
+
   def nested?
     self.class.accepted_nested_type?(@store[:type])
   end
 
+  def nesting
+    @store[:nested]
+  end
+
   def required?
     @store[:required]
   end
 
   def method_missing(name, *args)
-    return @store.send(name, *args) if respond_to_missing?(name)
+    return @store.public_send(name, *args) if respond_to_missing?(name)
     super
   end
 

data/lib/rails_api_doc/controller/parameter.rb

@@ -6,7 +6,7 @@ module RailsApiDoc::Controller::Parameter
 
   # Use parameter in controller to defined REQUEST parameter.
   # Adds it to repository: RailsApiDoc::Controller::Parameter::Repository
-  def parameter(name, options, &block)
+  def parameter(name, options = {}, &block)
     raise ArgumentError, 'Parameter already defined.' if repo.key?(name)
 
     validate_options(options, block_given?)
@@ -17,17 +17,9 @@ module RailsApiDoc::Controller::Parameter
   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
@@ -36,13 +28,18 @@ module RailsApiDoc::Controller::Parameter
     @repo || Repository[self]
   end
 
+  # adjust parameter values depending on parameter type
+  # 1. if nested - add nested values to parameter_data on :nested key
+  # 2. if enum - transform all values to_s
+  #    bcs all incoming controller parameters will be strings and there can be errors
   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
+    if Repository::Param.valid_nested?(parameter_data[:type], block_given?)
+      parameter_data = nested_parameter(parameter_data, &block)
+    elsif Repository::Param.valid_enum?(parameter_data[:type], parameter_data[:enum])
+      parameter_data[:enum].map!(:to_s)
+    end
+
+    repo[name] = Repository::Param.new(name, parameter_data)
   end
 
   def nested_parameter(parameter_data)

data/lib/rails_api_doc/controller/strong_params.rb

@@ -2,45 +2,70 @@
 # frozen_string_literal: true
 module RailsApiDoc::Controller::StrongParams
 
+  ParamIsRequired = Class.new(StandardError)
+
   def resource_params
     # accepted_params for permit
-    accepted_params = [{}]
-    loop_params(params, permitted_params, accepted_params)
-    params.permit(accepted_params)
+    params.permit(params_to_permit)
   end
 
   private
 
-  # loop through current level of params and add to permit level if
-  # all requirements met
-  # requirements are: 1) if required is set - param must be present and not empty
-  #                   2) if enum is set - param must equal predefined value
+  def params_to_permit
+    accepted_params = [{}]
+
+    loop_params(params, permitted_params, accepted_params)
+
+    accepted_params
+  end
+
+  # loop through current level of params and add to permit level if all requirements are met
+  #
+  # requirements are: 1) if required is set - param must be present and not empty => or error is raised
+  #                   2) if enum is set - param must equal predefined value => see Config::ValidateEnum
+  #                   3) if ary_object => see Config::ValidateAryObject
   #                   3) if config.check_params_type is set - param must be of required type
+  #
   # @accepted_params = [{}] - array with last member hash for nesting
   # @level_params - current nesting level params
   # @level_permitted_params - data for params permission
-  def loop_params(nested_controller_params, level_permitted_params, accepted_params)
+  def loop_params(params, level_permitted_params, accepted_params)
     level_permitted_params.each do |param_name, api_param_data|
-      controller_param = nested_controller_params[param_name]
+      controller_param = params[param_name]
+
+      check_required(param_name, controller_param, api_param_data)
+      #
+      # no value present && not required => go next
+      next unless controller_param
 
       next unless RailsApiDoc::Config::Validator.valid_param?(controller_param, api_param_data)
 
-      if api_param_data.nested?
-        level_accepted_params = accepted_params.last[param_name] = [{}]
-        next loop_params(controller_param, api_param_data, level_accepted_params)
+      # if settings is array
+      if api_param_data.ary_object?
+        controller_param.each do |single_controller_param|
+          _next_nesting_level(single_controller_param, param_data: api_param_data, current_accepted_params: accepted_params, param_name: param_name)
+        end
+      elsif api_param_data.nested?
+        _next_nesting_level(controller_param, param_data: api_param_data, current_accepted_params: accepted_params, param_name: param_name)
       else
         accepted_params.unshift(param_name)
       end
     end
   end
 
+  def _next_nesting_level(controller_param, param_data:, current_accepted_params:, param_name:)
+    level_accepted_params = current_accepted_params.last[param_name] = [{}]
+
+    loop_params(controller_param, param_data.nesting, level_accepted_params)
+  end
+
   def permitted_params
-    Parameter::Repository[self]
+    ::RailsApiDoc::Controller::Parameter::Repository[self.class]
   end
 
-  def check_required_ok?(param_data, param_config)
-    return true unless param_config.required?
-    !param_data.blank?
+  def check_required(param_name, param_data, param_config)
+    return unless param_config.required? && param_data.blank?
+    raise RailsApiDoc::Exception::ParamRequired, param_name
   end
 
 end

data/lib/rails_api_doc/engine.rb

@@ -5,9 +5,12 @@ require 'action_view'
 require 'jquery-rails'
 require 'slim'
 
+require_relative 'exception/param_required'
+
 require_relative 'controller'
 require_relative 'controller/strong_params'
 require_relative 'controller/attribute_parser'
+
 require_relative 'controller/parameter'
 require_relative 'controller/parameter/repository'
 require_relative 'controller/parameter/repository/param'

data/lib/rails_api_doc/exception/param_required.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+# :nodoc:
+module RailsApiDoc
+  module Exception
+    class ParamRequired < StandardError
+
+      def initialize(param_name)
+        @message = "#{param_name} is marked as required, but has no value."
+      end
+
+    end
+  end
+end

data/lib/rails_api_doc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 # author: Vadim Shaveiko <@vshaveyko>
 module RailsApiDoc
-  VERSION = '0.1.9'
+  VERSION = '0.2.0'
 end

data/lib/rails_api_doc.rb

@@ -1,8 +1,8 @@
 # author: Vadim Shaveiko <@vshaveyko>
 # frozen_string_literal: true
-module RailsApiDoc
+require 'rails_api_doc/config'
 
-  extend ActiveSupport::Autoload
+module RailsApiDoc
 
   class << self
 
@@ -11,7 +11,7 @@ module RailsApiDoc
     end
 
     def configuration
-      @_configuration ||= Configuration.new
+      @_configuration ||= Config.new
     end
 
     def reset_configuration
@@ -20,19 +20,6 @@ module RailsApiDoc
 
   end
 
-  autoload :Controller
-
-end
-
-# constants for defining in controllers
-# TODO: move to namespace ?
-class Bool
-end
-
-class Enum
-end
-
-class Nested
 end
 
 require 'rails_api_doc/version'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_api_documentation
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.0
 platform: ruby
 authors:
 - vs
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-23 00:00:00.000000000 Z
+date: 2016-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -158,8 +158,11 @@ files:
 - app/views/shared/_table.slim
 - config/routes.rb
 - lib/rails_api_doc.rb
+- lib/rails_api_doc/config.rb
+- lib/rails_api_doc/config/validate_ary_object.rb
+- lib/rails_api_doc/config/validate_enum.rb
+- lib/rails_api_doc/config/validate_type.rb
 - lib/rails_api_doc/config/validator.rb
-- lib/rails_api_doc/configuration.rb
 - lib/rails_api_doc/controller.rb
 - lib/rails_api_doc/controller/attribute_parser.rb
 - lib/rails_api_doc/controller/parameter.rb
@@ -170,6 +173,7 @@ files:
 - lib/rails_api_doc/controller/response_factory.rb
 - lib/rails_api_doc/controller/strong_params.rb
 - lib/rails_api_doc/engine.rb
+- lib/rails_api_doc/exception/param_required.rb
 - lib/rails_api_doc/version.rb
 homepage: https://github.com/vshaveyko/rails_api_doc
 licenses:

data/lib/rails_api_doc/configuration.rb

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