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.



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

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



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

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



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

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:



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

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



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

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