rails_api_documentation 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9f3a28fb24ee63994ecff8cfdef502e2ee6a07b9
-  data.tar.gz: c7a0dc69133680aa75d09d0fc2a1cbdd5ace98b3
+  metadata.gz: a72e86cdcaefec61dd47079acd6df5eb7ad88762
+  data.tar.gz: dc2ee37bbed89765494a3b697ab337db746aaefb
 SHA512:
-  metadata.gz: 6a313b7d46410b696f00d7f133d64d385f950c1d56d05ed383d39af1a438d0c2af164b1a064cb7932eeb46f0628dedf8acfacd87daf3af6c7edd0361d5efcf26
-  data.tar.gz: 4eb52929a55fcc97ab0096246dfd17c5315be9c4255ed4fce52549f2db29a10357f019bc6e5788eb861ea51bef382576980d97d2bedea4bd3adeda2dcc369e65
+  metadata.gz: 6a1d84265c02e6c7c588078cb27790bb1a231a6451aa35c3c24210b41a2ec62237deb611be3408346f66dbcd8e68fb6a44f8473194eedb77acc0f4e5e528a085
+  data.tar.gz: 43e6fb0376be3a10f0da24cf170bc42110b79869308e5d3b7ebaf19e59104b872e2c34365bc2647ba5e50ab6fb803e38115382579e704f56d4d6692153aeb1d7

data/README.md

@@ -22,7 +22,7 @@ Or install it yourself as:
 + 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
++ ```strong_params``` method that will filter incoming params for you
 
 ## Usage
 
@@ -56,7 +56,16 @@ To display api documentation on route '/api_doc' you need to:
           parameter :comment, type: :string
         end
       end
-      parameter :test, type: String, required: true
+      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
 
     end
   ```
@@ -75,7 +84,7 @@ To display api documentation on route '/api_doc' you need to:
 
     # controller action
     def create
-      Comment.create!(resource_params)
+      Comment.create!(strong_params)
     end
 
   ```
@@ -84,6 +93,52 @@ To display api documentation on route '/api_doc' you need to:
 
   Comment will be created with: `Comment(body='Comment body', title='Comment title', age=nil)`
 
+## Value
+
+  You can pass optional value argument to every parameter:
+
+  ```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.
+
+  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`
+
+  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.
+
+## Enum
+
+  When you defined parameter type as `:enum` you can pass `enum:` option. This will filter parameter by values provided.
+
+## Group common blocks
+
+  You can define parameters that have common fields this way:
+
+  ```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
+  ```
+
+  Pass common values as last optional arguments and uniq definitions as hash value.
+  All nesting parameters are applied to elements in blocks.
+
+  Something with same type can be defined like this:
+
+  ```ruby
+    parameter :name, :desc, type: :string
+  ```
+
 ## Types
 
   Parameter type may be one of these:

data/app/views/rails_api_doc/api_docs/_request_api_table.slim

@@ -2,4 +2,4 @@
 
 div[id="#{ctrl}.request" style="--row-count: #{request_headers.length}"]
 
-  = render 'shared/table', model: ctrl, rows: repo[ctrl], headers: request_headers, nesting: [], params: { api_type: :request }
+  = render 'shared/table', model: ctrl, rows: repo[ctrl.name], headers: request_headers, nesting: [], params: { api_type: :request }

data/app/views/rails_api_doc/api_docs/_response_api_table.slim

@@ -11,6 +11,6 @@ div.response-table[id="#{ctrl}.response"  style="--row-count: #{response_headers
       div.request-action-title
         = render 'shared/title', locals: { blue_title: route[:method], yellow_title: route[:url]}
 
-      - if rows = repo.load_template(ctrl, action)
+      - if rows = repo.load_attrs(ctrl, action)
 
         = render 'shared/table', model: ctrl, rows: rows, headers: response_headers, nesting: [], params: { api_action: action, api_type: :response }

data/app/views/shared/_table.slim

@@ -29,7 +29,7 @@ div.flex-table
           - if index.zero?
             span.ico ✏
             / = submit_tag ,name: 'destroy', class: 'ico destroy'
-            = link_to '❌' , api_doc_url(construct_destroy_param(row_values, params, nesting)), method: :delete,  class: 'destroy ico'
+            = link_to '❌' , api_doc_url(construct_destroy_param(row_values, params, nesting)), method: :delete,data: { confirm: 'Are you sure?' }, class: 'destroy ico'
             span.exit.ico ❌
             = submit_tag '✔'
 

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

@@ -5,19 +5,48 @@ module RailsApiDoc
     module Request
       module DSL
 
+        #
         # Use parameter in controller to define REQUEST parameter.
         # Adds it to repository: RailsApiDoc::Controller::Request::Repository
-        def parameter(name, options = {}, &block)
+        # Params can be defined in several ways:
+        # 1. parameter :name, type: :string
+        #
+        # 2. parameter {
+        #   dose_form_attributes: { model: 'Rxnorm::RxDoseForm' },
+        #   input_method_attributes: { model: 'TreatmentInfo::InputMethod' },
+        #   input_condition_attributes: { model: 'Drugs::InputCondition' },
+        #   input_duration_attributes: { model: 'Drugs::InputDuration' }
+        # }, type: :object do
+        #   parameter :id
+        #   parameter :name
+        # end
+        #
+        # 3. parameter :name, :code, type: :string
+        #
+        def parameter(*arguments, &block)
+          options = arguments.extract_options!
+
           raise ArgumentError, 'Parameter already defined.' if repo.key?(name)
 
           validate_options(options, block_given?)
 
-          define_parameter(name, options, &block)
+          arguments.each do |param|
+            # 2)
+            if param.is_a?(Hash)
+              param.each do |param_name, additional_options|
+                _options = options.merge(additional_options)
+
+                define_parameter(param_name, _options, &block)
+              end
+            else # 1), 3)
+              define_parameter(param, options, &block)
+            end
+          end
         end
 
         private
 
-        def validate_options(options, block_given)
+        def validate_options(options, _block_given)
           options.assert_valid_keys(RailsApiDoc::Controller::Param::VALID_KEYS)
 
           RailsApiDoc::Controller::Request::Param.valid_type?(options[:type])

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

@@ -4,11 +4,11 @@ class RailsApiDoc::Controller::Request::Factory
   class << self
 
     def repo
-      attributes = RailsApiDoc::Controller::Request::Repository.new
+      repo = RailsApiDoc::Controller::Request::Repository.new
 
-      attributes = merge_attributes_from_model attributes
+      repo.repo = merge_attributes_from_model repo.repo
 
-      attributes
+      repo
     end
 
     def registered_controllers
@@ -21,7 +21,7 @@ class RailsApiDoc::Controller::Request::Factory
     # do not mutate attributes
     #
     def merge_attributes_from_model(attributes)
-      RailsApiDoc::Model::AttributeMerger.new(attributes).call(api_type: 'request')
+      RailsApiDoc::Model::AttributeMerger.new(attributes, 'request').call
     end
 
   end

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

@@ -50,9 +50,9 @@ module RailsApiDoc
 
         def display_special
           spec = if enum?
-                  enum
-                elsif nested?
-                  model
+                   enum
+                 elsif nested? || model?
+                   model
                 end
 
           spec = spec.to_s + "(#{param.special})" if param&.special

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

@@ -8,11 +8,7 @@ class RailsApiDoc::Controller::Response::Factory
     # TODO: add more options later depending on app settings
     # TODO: rename to :load_repo
     def repo
-      attributes = RailsApiDoc::Controller::Response::Repository.new(repository.repo)
-
-      attributes = merge_attributes_from_model attributes
-
-      attributes
+      RailsApiDoc::Controller::Response::Repository.new(repository.repo)
     end
 
     def controllers
@@ -25,13 +21,6 @@ class RailsApiDoc::Controller::Response::Factory
       @repo ||= ::RailsApiDoc::Controller::Response::Rabl.new(controllers)
     end
 
-    #
-    # do not mutate attributes
-    #
-    def merge_attributes_from_model(attributes)
-      RailsApiDoc::Model::AttributeMerger.new(attributes).call(api_type: 'response')
-    end
-
   end
 
 end

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

@@ -7,7 +7,6 @@ module RailsApiDoc::Controller::Response::Headers
 
   RESPONSE_HEADERS = [
     NAME_HEADER,
-    TYPE_HEADER,
     VALUE_HEADER,
     DESC_HEADER
   ].reduce(&:merge).freeze

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
 # :nodoc:
 class RailsApiDoc::Controller::Response::Repository
 
@@ -5,7 +7,15 @@ class RailsApiDoc::Controller::Response::Repository
   include RailsApiDoc::Controller::Response::Headers
 
   def initialize(repo)
-    @repo = repo.clone.transform_values { |v| v.deep_dup }
+    @repo = repo.clone.transform_values(&:deep_dup)
+  end
+
+  def load_attrs(ctrl, action)
+    at = load_template(ctrl, action)&.nodes || {}
+
+    at = RailsApiDoc::Model::AttributeMerger.new(at, 'response').merge_action(action: action, ctrl: ctrl)
+
+    at
   end
 
   def load_template(ctrl, action)

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

@@ -1,14 +1,19 @@
-# :nodoc:
+# frozen_string_literal: true
+# author: Vadim Shaveiko <@vshaveyko>
 module RailsApiDoc
   module Controller
     module ResourceParams
-      module DSL
+      module DSL # :nodoc:
 
         include RailsApiDoc::Controller::ResourceParams::PermittedParams # implements params_to_permit
 
-        def resource_params
+        def strong_params(pars = params)
+          #
           # accepted_params for permit
-          params.permit(params_to_permit)
+          #
+          permitted = params_to_permit(pars)
+
+          pars.permit(permitted)
         end
 
       end

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

@@ -7,8 +7,8 @@ module RailsApiDoc
 
         private
 
-        def params_to_permit
-          _next_nesting_level(params, param_data: _permitted_params)
+        def params_to_permit(pars = params)
+          _next_nesting_level(pars, param_data: _permitted_params)
         end
 
         def _permitted_params
@@ -32,7 +32,6 @@ module RailsApiDoc
           level_accepted_params
         end
 
-
         #
         # loop through current level of params and add to permit level if all requirements are met
         #
@@ -47,6 +46,10 @@ module RailsApiDoc
         #
         def loop_params(params, level_permitted_params, accepted_params)
           level_permitted_params.each do |param_name, api_param_data|
+            if api_param_data.value&.respond_to?(:call)
+              params[param_name] = api_param_data.value.call(params[param_name])
+            end
+
             controller_param = params[param_name]
 
             _check_required(param_name, controller_param, api_param_data) # raise if required and no value
@@ -63,7 +66,6 @@ module RailsApiDoc
                                     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,

data/lib/rails_api_doc/model/attribute_merger.rb

@@ -6,53 +6,58 @@ class RailsApiDoc::Model::AttributeMerger
   MODEL = RailsApiDoc::ApiDatum
   MERGABLE_FIELDS = [:type, :desc, :action_type].freeze
 
+  @@data = MODEL.all
+
   #
   # do not mutate attributes
   #
   # please - impossible
   #
-  def initialize(attributes)
-    @attrs = attributes
+  def initialize(attributes, api_type)
+    @attrs = attributes.stringify_keys
+    @api_type = api_type
   end
 
-  def call(api_type:)
-    @api_type = api_type
+  def merge_action(action:, ctrl:)
+    merge_data = @@data.select { |d| d.api_type == @api_type && d.api_action == action.to_s && d.nesting.first == ctrl.name }
 
-    api_params = MODEL.where(api_type: api_type).all.each do |param|
-      _add_nested_param(param)
+    merge_data.each do |param|
+      _add_nested_param(param, param.nesting[1..-1], @attrs)
     end
 
     @attrs
   end
 
-  private
+  def call
+    api_params = @@data.select { |d| d.api_type == @api_type }.each do |param|
+      #
+      # nesting should be present for parameter to appear
+      #
+      next unless param.name && param.nesting.present?
 
-  def _add_nested_param(param)
-    # nesting should be present for parameter to appear
-    return if param.nesting.blank?
+      attrs, nesting, name = _parse_settings(param)
 
-    attrs, nesting, name = _parse_settings(param)
+      _add_nested_param(param, nesting, attrs)
+    end
 
-    return unless name
+    @attrs
+  end
+
+  private
 
-    ctrl_param = _find_param(nesting, name, attrs)
+  def _add_nested_param(param, nesting, attrs)
+    ctrl_param = _find_param(nesting, param.name, attrs)
 
     ctrl_param.param = param
     # _merge_data_to_param(ctrl_param, param)
   end
 
   def _parse_settings(param)
-    ctrl = param.nesting[0].constantize
+    ctrl = param.nesting[0]
     nesting = param.nesting[1..-1]
     name = param.name&.to_sym
     attrs = @attrs[ctrl]
 
-    #
-    # making exception
-    # until request parameters are not split by actions
-    #
-    attrs = attrs[param.api_action] if @api_type == 'response'
-
     [attrs, nesting, name]
   end
 
@@ -82,18 +87,18 @@ class RailsApiDoc::Model::AttributeMerger
     end
   end
 
-  def _find_param(nesting, name, attrs)
-    nesting.each do |model|
-      nested_attrs = attrs.each_value.detect { |v| v.nested? && v.model == model }
+  def _find_param(nest, name, attrs)
+    nest.each do |model|
+      #
+      # model on different fields because of wrong nesting sturcture for request
+      # TODO: fix this later
+      #
+      nested_attrs = attrs.detect { |k, v| v.nested? && (v.model == model || k.to_s == model)  }
 
       attrs = nested_attrs ? nested_attrs : _define_nesting_level(attrs, name, model)
     end
 
-    if attrs[name]
-      attrs[name]
-    else
-      attrs[name] = _init_param_for_api_type(name)
-    end
+    attrs[name] ||= _init_param_for_api_type(name, {})
   end
 
   def _define_nesting_level(attrs, name, model)
@@ -123,7 +128,7 @@ class RailsApiDoc::Model::AttributeMerger
     if @api_type == 'request'
       RailsApiDoc::Controller::Request::Param.new(name, options, is_new: true)
     elsif @api_type == 'response'
-      RailsApiDoc::Controller::Response::Param.new(name, name, options[:nested], options[:model], '', options[:type], is_new: true)
+      RailsApiDoc::Controller::Response::Param.new(name, name, options[:nested], options[:model], nil, options[:type], is_new: true)
     end
   end
 

data/lib/rails_api_doc/model/attribute_parser.rb

@@ -18,6 +18,7 @@ class RailsApiDoc::Model::AttributeParser
         action_type: params[:action],
         nesting: params[:nesting],
         api_type: params[:api_type],
+        api_action: params[:api_action],
         id: params[:id]
       }.compact
     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.1'
+  VERSION = '0.3.2'
 end

data/lib/rails_api_doc.rb

@@ -1,9 +1,10 @@
 # author: Vadim Shaveiko <@vshaveyko>
 # frozen_string_literal: true
 module RailsApiDoc
-  NESTED_TYPES = [:ary_object, :object, :model].freeze
+  
+  NESTED_TYPES = [:ary_object, :object, :json].freeze
 
-  STRAIGHT_TYPES = [:bool, :string, :integer, :array, :datetime, :enum].freeze
+  STRAIGHT_TYPES = [:bool, :string, :integer, :array, :datetime, :enum, :model].freeze
 
   ACCEPTED_TYPES = (NESTED_TYPES + STRAIGHT_TYPES).freeze
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_api_documentation
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - vs
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-12 00:00:00.000000000 Z
+date: 2016-12-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler