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.



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

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



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

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 parmas, you can specify :as => :create or :update to explicitly say how it should behave



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

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:



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

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



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
442
 
# File 'lib/apipie/dsl_definition.rb', line 405

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