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.



427
428
429
 
# File 'lib/apipie/dsl_definition.rb', line 427

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



325
326
327
328
329
330
331
332
 
# File 'lib/apipie/dsl_definition.rb', line 325

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



346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'lib/apipie/dsl_definition.rb', line 346

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:



334
335
336
337
338
339
 
# File 'lib/apipie/dsl_definition.rb', line 334

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



386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
 
# File 'lib/apipie/dsl_definition.rb', line 386

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