rails_api_documentation 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a72e86cdcaefec61dd47079acd6df5eb7ad88762
-  data.tar.gz: dc2ee37bbed89765494a3b697ab337db746aaefb
+  metadata.gz: aa57f61a95e060eff72a6089f4e5806d7246bfe9
+  data.tar.gz: 6cafddf29e9049a7a3e75b5817f4bdc95a600c87
 SHA512:
-  metadata.gz: 6a1d84265c02e6c7c588078cb27790bb1a231a6451aa35c3c24210b41a2ec62237deb611be3408346f66dbcd8e68fb6a44f8473194eedb77acc0f4e5e528a085
-  data.tar.gz: 43e6fb0376be3a10f0da24cf170bc42110b79869308e5d3b7ebaf19e59104b872e2c34365bc2647ba5e50ab6fb803e38115382579e704f56d4d6692153aeb1d7
+  metadata.gz: a340764a01562dc0417d0289b66c0cfa7cbaa6cae3ca057adbc1fdffb93c35fc35e44b2f785e5c7de4273b11846cd460c8b5251013603e007c278ddf468e0c70
+  data.tar.gz: 23fb0e13df0227c92ef22498055b03278e63e3903b849c6951a4204b6d17bd49835d031830c366982355f85b89c60e6dee48ca4b8d60a537676ae7991d1179f5

data/README.md

@@ -1,5 +1,4 @@
-
-# RailsApiDoc
+# RailsApiDoc [![CircleCI](https://circleci.com/gh/vshaveyko/rails_api_doc/tree/master.svg?style=svg&circle-token=cc544085bb94b3f8613cfab79e9618bf20ce7138)](https://circleci.com/gh/vshaveyko/rails_api_doc/tree/master)
 
 ## Installation
 
@@ -19,159 +18,166 @@ Or install it yourself as:
 
 ## Features
 
-+ displaying application api if used in one of correct ways
++ Displaying application api if used in one of the correct ways.
   ![alt tag](https://raw.githubusercontent.com/vshaveyko/rails_api_doc/master/preview.png)
-+ Integration with Rabl if it is bundled
-+ ```strong_params``` method that will filter incoming params for you
++ Integration with Rabl if it is bundled.
++ `strong_params` method that will filter incoming params for you.
 
 ## Usage
 
 To display api documentation on route '/api_doc' you need to:
 
-0. config/application.rb ->
+1. config/application.rb ->
+```ruby
+require 'rails_api_doc'
+```
+
+2. config/routes.rb ->
 ```ruby
-  require 'rails_api_doc'
+mount RailsApiDoc::Engine => '/api_doc'
 ```
-1. config/routes.rb ->
-  ```ruby
-    mount RailsApiDoc::Engine => '/api_doc'
-  ```
-
-2. define request parameters. Example:
-  ```ruby
-    class AuthorsController < ApplicationController
-
-      has_scope :article_id, :name
-
-      # Define parameters with type and nested options
-      # Article and Datum are usual ActiveRecord models
-      parameter :age, type: :integer
-      parameter :name, type: :string, required: true
-      parameter :articles_attributes, type: :ary_object, model: 'Article' do
-        parameter :title, type: :string
-        parameter :body, type: :string, required: true
-        parameter :rating, type: :enum, enum: [1, 2, 3]
-        parameter :data_attributes, type: :object, model: 'Datum' do
-          parameter :creation_date, type: :datetime
-          parameter :comment, type: :string
-        end
-      end
-      parameter :test, type: :string, required: true
-
-      parameter({
-        articles_attributes: { model: 'Article', type: :ary_object },
-        data_attributes: { model: 'Datum' },
-        comments_attributes: { model: 'Comment', type: :ary_object }
-      }, type: :object) do
-        parameter :id
-        parameter :name
-      end
 
+3. define request parameters. Example:
+```ruby
+class AuthorsController < ApplicationController
+
+  has_scope :article_id, :name
+
+  # Define parameters with type and nested options
+  # Article and Datum are usual ActiveRecord models
+  parameter :age, type: :integer
+  parameter :name, type: :string, required: true
+  parameter :articles_attributes, type: :ary_object, model: 'Article' do
+    parameter :title, type: :string
+    parameter :body, type: :string, required: true
+    parameter :rating, type: :enum, enum: [1, 2, 3]
+    parameter :data_attributes, type: :object, model: 'Datum' do
+      parameter :creation_date, type: :datetime
+      parameter :comment, type: :string
     end
-  ```
-3. go to localhost:3000/api_doc
+  end
+  parameter :test, type: :string, required: true
+
+  parameter({
+    articles_attributes: { model: 'Article', type: :ary_object },
+    data_attributes: { model: 'Datum' },
+    comments_attributes: { model: 'Comment', type: :ary_object }
+  }, type: :object) do
+    parameter :id
+    parameter :name
+  end
 
-## Strong params
+end
+```
 
-  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:
+4. go to localhost:3000/api_doc
 
-  ```ruby
+## Strong params
 
-    parameter :body, type: :string
-    parameter :title, type: :string
+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:
 
-    # controller action
-    def create
-      Comment.create!(strong_params)
-    end
+```ruby
+parameter :body, type: :string
+parameter :title, type: :string
 
-  ```
+# controller action
+def create
+  Comment.create!(strong_params)
+end
+```
 
-  and if request is `POST '/comments', params: { body: 'Comment body', title: 'Comment title', age: 34 }`
+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)`
+Comment will be created with: `Comment(body='Comment body', title='Comment title', age=nil)`
 
 ## Value
 
-  You can pass optional value argument to every parameter:
+You can pass optional value argument to every parameter:
 
-  ```ruby
-    parameter :val, type: :integer, value: -> (request_value) { 5 }
-  ```
+```ruby
+parameter :val, type: :integer, value: -> (request_value) { 5 }
+```
 
-  on every matching request value in this field will be overriden by value returned by proc.
+on every matching request value in this field will be overriden by value returned by proc.
 
-  value field expecting anything that will respond to `:call` and can accept one argument(param value from request)
+value field expecting anything that will respond to `:call` and can accept one argument(param value from request)
 
-  you should expect that value passed can be `nil`
+you should expect that value passed can be `nil`
 
-  This can be used to force values on some fields, or modify values passed to request in some ways.
+This can be used to force values on some fields, or modify values passed to request in some ways.
 
-  E.g. you want to force current_user_id on model creation instead of passing it from frontend.
+E.g. you want to force current_user_id on model creation instead of passing it from frontend.
 
 ## Enum
 
-  When you defined parameter type as `:enum` you can pass `enum:` option. This will filter parameter by values provided.
+When you defined parameter type as `:enum` you can pass `enum:` option. This will filter parameter by values provided.
 
-## Group common blocks
+E.g.:
 
-  You can define parameters that have common fields this way:
+```ruby
+parameter :rating, type: :enum, enum: [1, 2, 3]
+```
 
-  ```ruby
-    parameter({
-      articles_attributes: { model: 'Article', type: :ary_object },
-      data_attributes: { model: 'Datum' },
-      comments_attributes: { model: 'Comment', type: :ary_object }
-    }, type: :object) do
-      parameter :id
-      parameter :name
-    end
-  ```
+All enum values are parsed as strings, since controller params are always strings. Still you may write them as you want. Every member of enum array will be replaced with `&:to_s` version.
 
-  Pass common values as last optional arguments and uniq definitions as hash value.
-  All nesting parameters are applied to elements in blocks.
+## Group common blocks
 
-  Something with same type can be defined like this:
+You can define parameters that have common fields this way:
 
-  ```ruby
-    parameter :name, :desc, type: :string
-  ```
+```ruby
+parameter({
+  articles_attributes: { model: 'Article', type: :ary_object },
+  data_attributes: { model: 'Datum' },
+  comments_attributes: { model: 'Comment', type: :ary_object }
+}, type: :object) do
+  parameter :id
+  parameter :name
+end
+```
 
-## Types
+Pass common values as last optional arguments and uniq definitions as hash value.
+All nesting parameters are applied to elements in blocks.
 
-  Parameter type may be one of these:
+Something with same type can be defined like this:
 
-  ```ruby
+```ruby
+parameter :name, :desc, type: :string
+```
 
-   # 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)
+## 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
+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)
+:model - model reference e.g. :author_id, add model value as model: 'Author' after this
+
+# 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
+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
@@ -179,9 +185,9 @@ 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
+response :data, type: :model, model: Datum do
+  extends DataController, action: :show
+end
 ```
 + dsl for extending request parameters
 ```ruby

data/lib/rails_api_doc/config.rb

@@ -3,7 +3,12 @@
 # :nodoc:
 class RailsApiDoc::Config
 
-  attr_accessor :check_params_type
+  attr_accessor :check_params_type, :params_dir
+
+  # init default values
+  def initialize
+    @params_dir = 'params'
+  end
 
   def check_params_type=(value)
     if value

data/lib/rails_api_doc/controller/request/dsl.rb

@@ -23,6 +23,8 @@ module RailsApiDoc
         #
         # 3. parameter :name, :code, type: :string
         #
+        # 4. param :name, :string, model: 'Name'
+        #
         def parameter(*arguments, &block)
           options = arguments.extract_options!
 
@@ -30,6 +32,9 @@ module RailsApiDoc
 
           validate_options(options, block_given?)
 
+          # 4)
+          return if second_argument_type_def(options, arguments)
+
           arguments.each do |param|
             # 2)
             if param.is_a?(Hash)
@@ -44,6 +49,9 @@ module RailsApiDoc
           end
         end
 
+        alias param parameter
+        alias req parameter
+
         private
 
         def validate_options(options, _block_given)
@@ -73,12 +81,32 @@ module RailsApiDoc
         end
 
         def nested_parameter(parameter_data)
-          _backup_repo = @repo
+          backup_repo = @repo
           @repo = {}
           yield
           parameter_data.merge(nested: @repo)
         ensure
-          @repo = _backup_repo
+          @repo = backup_repo
+        end
+
+        #
+        # Checks whetjher parameters can be defined by type 4)
+        # if possible - do it
+        # otherwise pass next
+        #
+        def second_argument_type_def(options, args)
+          is_ok = second_argument_is_type?(args)
+
+          return false unless is_ok
+          param = args[0]
+          options[:type] = args[1]
+
+          define_parameter(param, options, &block)
+          true
+        end
+
+        def second_argument_is_type?(args)
+          RailsApiDoc::ACCEPTED_TYPES.include?(args[1]&.to_sym)
         end
 
       end

data/lib/rails_api_doc/controller/strong_params/dsl.rb

@@ -8,9 +8,6 @@ module RailsApiDoc
         include RailsApiDoc::Controller::ResourceParams::PermittedParams # implements params_to_permit
 
         def strong_params(pars = params)
-          #
-          # accepted_params for permit
-          #
           permitted = params_to_permit(pars)
 
           pars.permit(permitted)

data/lib/rails_api_doc/controller/strong_params/permitted_params.rb

@@ -5,12 +5,15 @@ module RailsApiDoc
     module ResourceParams
       module PermittedParams
 
-        private
-
+        #
+        # accepted_params for permit
+        #
         def params_to_permit(pars = params)
           _next_nesting_level(pars, param_data: _permitted_params)
         end
 
+        private
+
         def _permitted_params
           ::RailsApiDoc::Controller::Request::Repository[self.class]
         end
@@ -24,7 +27,9 @@ module RailsApiDoc
           level_accepted_params = [{}]
 
           if param_name && current_accepted_params # no param name and current_accepted_params on first iteration
-            current_accepted_params.last[param_name] = level_accepted_params
+            current_accepted_params.last[param_name] ||= level_accepted_params
+
+            level_accepted_params = current_accepted_params.last[param_name]
           end
 
           loop_params(controller_param, param_data, level_accepted_params)
@@ -46,33 +51,43 @@ module RailsApiDoc
         #
         def loop_params(params, level_permitted_params, accepted_params)
           level_permitted_params.each do |param_name, api_param_data|
+            next if accepted_params.include?(param_name) || accepted_params.last.key?(param_name)
+
             if api_param_data.value&.respond_to?(:call)
-              params[param_name] = api_param_data.value.call(params[param_name])
+              params[param_name] = instance_eval(&api_param_data.value)
             end
 
             controller_param = params[param_name]
 
             _check_required(param_name, controller_param, api_param_data) # raise if required and no value
 
+            #
             # no value present && not required => skip
-            next unless controller_param
+            #
+            # nil value is still ok params.key?(param_key) returns true if we have params = { param_key => nil }
+            #
+            next unless params.key?(param_name)
 
             # value present but not valid for this type => skip
             next unless RailsApiDoc::Config::Validator.valid_param?(controller_param, api_param_data)
 
             if api_param_data.ary_object? # controller_param value should be array of objects
-              controller_param.each do |single_controller_param|
+              controller_param&.each do |single_controller_param|
                 _next_nesting_level(single_controller_param,
                                     param_data: api_param_data.nested,
                                     current_accepted_params: accepted_params,
                                     param_name: param_name)
               end
             elsif api_param_data.nested? # value should be nested object
-              _next_nesting_level(controller_param,
-                                  param_data: api_param_data.nested,
-                                  current_accepted_params: accepted_params,
-                                  param_name: param_name)
+              if controller_param
+                _next_nesting_level(controller_param,
+                                    param_data: api_param_data.nested,
+                                    current_accepted_params: accepted_params,
+                                    param_name: param_name)
+              end
 
+            elsif api_param_data.array?
+              accepted_params.last[param_name] = []
             else # all other options
               accepted_params.unshift(param_name)
             end

data/lib/rails_api_doc/model/attribute_parser.rb

@@ -54,7 +54,7 @@ class RailsApiDoc::Model::AttributeParser
     def parse_special(type, special)
       return unless special.present? && type
 
-      if type == :enum
+      if type.to_sym == :enum
         parse_enum(special) # parse as enum array value
       elsif RailsApiDoc::NESTED_TYPES.include?(type.to_sym)
         special.capitalize # parse as model name

data/lib/rails_api_doc/params/dsl.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+# :nodoc:
+module RailsApiDoc::Params::DSL
+
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  #:nodoc:
+  module ClassMethods
+    def parameter_class=(value)
+      @parameter_class = value
+    end
+
+    def parameter_class
+      @parameter_class ||= RailsApiDoc::Params::Finder.new(self).call
+    end
+  end
+
+  def ctrl_strong_params
+    @ctrl_strong_params ||= ctrl_parameters.strong_params(params)
+  end
+
+  def ctrl_parameters
+    @ctrl_parameters ||= self.class.parameter_class.new
+  end
+
+end

data/lib/rails_api_doc/params/finder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+# :nodoc:
+class RailsApiDoc::Params::Finder
+
+  SUFFIX = 'Parameter'
+
+  def initialize(object)
+    @object = object
+  end
+
+  def call
+    klass = find_class_name(@object).name.sub(/Ctrl$/, '')
+
+    "#{klass}#{SUFFIX}".constantize
+  end
+
+  private
+
+  def find_class_name(subject)
+    if subject.respond_to?(:model_name)
+      subject.model_name
+    elsif subject.class.respond_to?(:model_name)
+      subject.class.model_name
+    elsif subject.is_a?(Class)
+      subject
+    elsif subject.is_a?(Symbol)
+      subject.to_s.camelize
+    else
+      subject.class
+    end
+  end
+
+end

data/lib/rails_api_doc/params/main.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
+# :nodoc:
+class RailsApiDoc::Params
+
+  include RailsApiDoc::Controller::ResourceParams::DSL
+  extend RailsApiDoc::Controller::Request::DSL
+
+end

data/lib/rails_api_doc/railtie.rb

@@ -1,13 +1,17 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
 module RailsApiDoc
   class Railtie < Rails::Railtie
+
     initializer 'api_doc.controller_additions' do
       ActiveSupport.on_load :action_controller do
-
         include RailsApiDoc::Controller::ResourceParams::DSL
 
         extend RailsApiDoc::Controller::Request::DSL
 
+        include RailsApiDoc::Params::DSL
       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.3.2'
+  VERSION = '0.3.3'
 end

data/lib/rails_api_doc.rb

@@ -1,13 +1,15 @@
 # author: Vadim Shaveiko <@vshaveyko>
 # frozen_string_literal: true
 module RailsApiDoc
-  
+
   NESTED_TYPES = [:ary_object, :object, :json].freeze
 
   STRAIGHT_TYPES = [:bool, :string, :integer, :array, :datetime, :enum, :model].freeze
 
   ACCEPTED_TYPES = (NESTED_TYPES + STRAIGHT_TYPES).freeze
 
+  _dir = 'rails_api_doc/'
+
   module Controller
     _dir = 'rails_api_doc/controller/'
 
@@ -42,6 +44,16 @@ module RailsApiDoc
     end
   end
 
+  require _dir + 'params/main'
+  class Params
+
+    _dir = 'rails_api_doc/params/'
+
+    autoload :DSL, _dir + 'dsl'
+    autoload :Finder, _dir + 'finder'
+
+  end
+
   module Model
     _dir = 'rails_api_doc/model/'
 
@@ -49,7 +61,7 @@ module RailsApiDoc
     autoload :AttributeParser, _dir + 'attribute_parser'
   end
 
-  require 'rails_api_doc/config'
+  require _dir + 'config'
   class Config
 
     _dir = 'rails_api_doc/config/'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_api_documentation
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - vs
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-14 00:00:00.000000000 Z
+date: 2017-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -184,6 +184,9 @@ files:
 - lib/rails_api_doc/exception/param_required.rb
 - lib/rails_api_doc/model/attribute_merger.rb
 - lib/rails_api_doc/model/attribute_parser.rb
+- lib/rails_api_doc/params/dsl.rb
+- lib/rails_api_doc/params/finder.rb
+- lib/rails_api_doc/params/main.rb
 - lib/rails_api_doc/railtie.rb
 - lib/rails_api_doc/version.rb
 homepage: https://github.com/vshaveyko/rails_api_doc
@@ -193,7 +196,7 @@ metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
-- lib
+- lib/rails_api_doc.rb
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -206,7 +209,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: Nice API doc.