Module: Apipie::DSL::Param

Included in:
Concern, Controller, ResourceDescriptionDsl, ResponseDescription, ResponseDescription::ResponseObject, Validator::HashValidator
Defined in:
lib/apipie/dsl_definition.rb

Overview

this describes the params, it’s in separate module because it’s used in Validators as well

Instance Method Summary collapse

Instance Method Details

#_default_param_group_scope ⇒ Object

where the group definition should be looked up when no scope given. This is expected to return a controller.



445
446
447
 
# File 'lib/apipie/dsl_definition.rb', line 445

def _default_param_group_scope
  self
end

#param(param_name, validator, desc_or_options = nil, options = {}, &block) ⇒ Object

Describe method’s parameter

Example:

param :greeting, String, :desc => "arbitrary text", :required => true
def hello_world(greeting)
  puts greeting
end



343
344
345
346
347
348
349
350
 
# File 'lib/apipie/dsl_definition.rb', line 343

def param(param_name, validator, desc_or_options = nil, options = {}, &block) #:doc:
  return unless Apipie.active_dsl?
  _apipie_dsl_data[:params] << [param_name,
                                validator,
                                desc_or_options,
                                options.merge(:param_group => @_current_param_group),
                                block]
end

#param_group(name, scope_or_options = nil, options = {}) ⇒ Object

Reuses param group for this method. The definition is looked up in scope of this controller. If the group was defined in different controller, the second param can be used to specify it. when using action_aware params, you can specify :as => :create or :update to explicitly say how it should behave



364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
 
# File 'lib/apipie/dsl_definition.rb', line 364

def param_group(name, scope_or_options = nil, options = {})
  if scope_or_options.is_a? Hash
    options.merge!(scope_or_options)
    scope = options[:scope]
  else
    scope = scope_or_options
  end
  scope ||= _default_param_group_scope

  @_current_param_group = {
    :scope => scope,
    :name => name,
    :options => options,
    :from_concern => scope.apipie_concern?
  }
  self.instance_exec(&Apipie.get_param_group(scope, name))
ensure
  @_current_param_group = nil
end

#property(param_name, validator, desc_or_options = nil, options = {}, &block) ⇒ Object

:doc:



352
353
354
355
356
357
 
# File 'lib/apipie/dsl_definition.rb', line 352

def property(param_name, validator, desc_or_options = nil, options = {}, &block) #:doc:
  return unless Apipie.active_dsl?
  options[:only_in] ||= :response
  options[:required] = true if options[:required].nil?
  param(param_name, validator, desc_or_options, options, &block)
end

#returns(pgroup_or_options, desc_or_options = nil, options = {}, &block) ⇒ Object

Describe possible responses

Example:

  def_param_group :user do
    param :user, Hash do
      param :name, String
    end
  end

returns :user, "the speaker"
returns "the speaker" do
     param_group: :user
end
returns :param_group => :user, "the speaker"
returns :user, :code => 201, :desc => "the created speaker record"
returns :array_of => :user, "many speakers"
def hello_world
  render json: {user: {name: "Alfred"}}
end



404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
 
# File 'lib/apipie/dsl_definition.rb', line 404

def returns(pgroup_or_options, desc_or_options = nil, options = {}, &block) #:doc:
  return unless Apipie.active_dsl?


  if desc_or_options.is_a? Hash
    options.merge!(desc_or_options)
  elsif !desc_or_options.nil?
    options[:desc] = desc_or_options
  end

  if pgroup_or_options.is_a? Hash
    options.merge!(pgroup_or_options)
  else
    options[:param_group] = pgroup_or_options
  end

  code = options[:code] || 200
  scope = options[:scope] || _default_param_group_scope
  descriptor = options[:param_group] || options[:array_of]

  if block.nil?
    if descriptor.is_a? ResponseDescriptionAdapter
      adapter = descriptor
    elsif descriptor.respond_to? :describe_own_properties
      adapter = ResponseDescriptionAdapter.from_self_describing_class(descriptor)
    else
      begin
        block = Apipie.get_param_group(scope, descriptor) if descriptor
      rescue
        raise "No param_group or self-describing class named #{descriptor}"
      end
    end
  elsif descriptor
    raise "cannot specify both block and param_group"
  end

  _apipie_dsl_data[:returns][code] = [options, scope, block, adapter]
end