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.



442
443
444
 
# File 'lib/apipie/dsl_definition.rb', line 442

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



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

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



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

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:



349
350
351
352
353
354
 
# File 'lib/apipie/dsl_definition.rb', line 349

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



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

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