Class: Apipie::ParamDescription

Inherits:
Object
  • Object
show all
Defined in:
lib/apipie/param_description.rb,
lib/apipie/param_description/deprecation.rb

Overview

method parameter description

name - method name (show) desc - description required - boolean if required validator - Validator::BaseValidator subclass

Defined Under Namespace

Classes: Deprecation

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(method_description, name, validator, desc_or_options = nil, options = {}, &block) ⇒ ParamDescription

Returns a new instance of ParamDescription.

Raises:

  • (ArgumentError) 


42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/apipie/param_description.rb', line 42

def initialize(method_description, name, validator, desc_or_options = nil, options = {}, &block)

  if desc_or_options.is_a?(Hash)
    options = options.merge(desc_or_options)
  elsif desc_or_options.is_a?(String)
    options[:desc] = desc_or_options
  elsif !desc_or_options.nil?
    raise ArgumentError.new("param description: expected description or options as 3rd parameter")
  end

  options.symbolize_keys!

  # we save options to know what was passed in DSL
  @options = options
  if @options[:param_group]
    @from_concern = @options[:param_group][:from_concern]
  end

  if validator.is_a?(Hash)
    @options.merge!(validator.select{|k,v| k != :array_of })
  end

  @method_description = method_description
  @name = concern_subst(name)
  @as = options[:as] || @name
  @desc = preformat_text(@options[:desc])

  @parent = @options[:parent]
  @metadata = @options[:meta]

  @required = is_required?

  @response_only = (@options[:only_in] == :response)
  @request_only = (@options[:only_in] == :request)
  raise ArgumentError.new("'#{@options[:only_in]}' is not a valid value for :only_in") if (!@response_only && !@request_only) && @options[:only_in].present?

  @show = if @options.key? :show
    @options[:show]
  else
    true
  end

  @allow_nil = @options[:allow_nil] || false
  @allow_blank = @options[:allow_blank] || false

  action_awareness

  if validator
    if (validator != Hash) && (validator.is_a? Hash) && (validator[:array_of])
      @is_array = true
      validator = validator[:array_of]
      raise "an ':array_of =>' validator is allowed exclusively on response-only fields" unless @response_only
    end
    @validator = Validator::BaseValidator.find(self, validator, @options, block)
    raise "Validator for #{validator} not found." unless @validator
  end

  @validations = Array(options[:validations]).map {|v| concern_subst(Apipie.markup_to_html(v)) }

  @additional_properties = @options[:additional_properties]
  @deprecated = @options[:deprecated] || false
end

Instance Attribute Details

#additional_properties ⇒ Object (readonly)

Returns the value of attribute additional_properties.



12
13
14
 
# File 'lib/apipie/param_description.rb', line 12

def additional_properties
  @additional_properties
end

#allow_blank ⇒ Object (readonly)

Returns the value of attribute allow_blank.



11
12
13
 
# File 'lib/apipie/param_description.rb', line 11

def allow_blank
  @allow_blank
end

#allow_nil ⇒ Object (readonly)

Returns the value of attribute allow_nil.



11
12
13
 
# File 'lib/apipie/param_description.rb', line 11

def allow_nil
  @allow_nil
end

#as ⇒ Object (readonly)

Returns the value of attribute as.



11
12
13
 
# File 'lib/apipie/param_description.rb', line 11

def as
  @as
end

#desc ⇒ Object (readonly)

Returns the value of attribute desc.



11
12
13
 
# File 'lib/apipie/param_description.rb', line 11

def desc
  @desc
end

#is_array ⇒ Object (readonly) Also known as: is_array?

Returns the value of attribute is_array.



12
13
14
 
# File 'lib/apipie/param_description.rb', line 12

def is_array
  @is_array
end

#metadata ⇒ Object (readonly)

Returns the value of attribute metadata.



11
12
13
 
# File 'lib/apipie/param_description.rb', line 11

def metadata
  @metadata
end

#method_description ⇒ Object (readonly)

Returns the value of attribute method_description.



11
12
13
 
# File 'lib/apipie/param_description.rb', line 11

def method_description
  @method_description
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



11
12
13
 
# File 'lib/apipie/param_description.rb', line 11

def name
  @name
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



11
12
13
 
# File 'lib/apipie/param_description.rb', line 11

def options
  @options
end

#parent ⇒ Object

Returns the value of attribute parent.



13
14
15
 
# File 'lib/apipie/param_description.rb', line 13

def parent
  @parent
end

#request_only ⇒ Object (readonly) Also known as: request_only?

Returns the value of attribute request_only.



11
12
13
 
# File 'lib/apipie/param_description.rb', line 11

def request_only
  @request_only
end

#required ⇒ Object

Returns the value of attribute required.



13
14
15
 
# File 'lib/apipie/param_description.rb', line 13

def required
  @required
end

#response_only ⇒ Object (readonly) Also known as: response_only?

Returns the value of attribute response_only.



11
12
13
 
# File 'lib/apipie/param_description.rb', line 11

def response_only
  @response_only
end

#show ⇒ Object (readonly)

Returns the value of attribute show.



11
12
13
 
# File 'lib/apipie/param_description.rb', line 11

def show
  @show
end

#validations ⇒ Object (readonly)

Returns the value of attribute validations.



11
12
13
 
# File 'lib/apipie/param_description.rb', line 11

def validations
  @validations
end

#validator ⇒ Object (readonly)

Returns the value of attribute validator.



11
12
13
 
# File 'lib/apipie/param_description.rb', line 11

def validator
  @validator
end

Class Method Details

.from_dsl_data(method_description, args) ⇒ Object 



19
20
21
22
23
24
25
26
27
 
# File 'lib/apipie/param_description.rb', line 19

def self.from_dsl_data(method_description, args)
  param_name, validator, desc_or_options, options, block = args
  Apipie::ParamDescription.new(method_description,
                               param_name,
                               validator,
                               desc_or_options,
                               options,
                               &block)
end

.merge(target_params, source_params) ⇒ Object 



215
216
217
218
219
220
221
 
# File 'lib/apipie/param_description.rb', line 215

def self.merge(target_params, source_params)
  params_to_merge, params_to_add = source_params.partition do |source_param|
    target_params.any? { |target_param| source_param.name == target_param.name }
  end
  unify(target_params + params_to_merge)
  target_params.concat(params_to_add)
end

.unify(params) ⇒ Object

merge param descriptions. Allows defining hash params on more places (e.g. in param_groups). For example:

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

param_group :user
param :user, Hash do
  param :password, String
end



208
209
210
211
212
213
 
# File 'lib/apipie/param_description.rb', line 208

def self.unify(params)
  ordering = params.map(&:name)
  params.group_by(&:name).map do |name, param_descs|
    param_descs.reduce(&:merge_with)
  end.sort_by { |param| ordering.index(param.name) }
end

Instance Method Details

#==(other) ⇒ Object 



33
34
35
36
37
38
39
40
 
# File 'lib/apipie/param_description.rb', line 33

def ==(other)
  return false unless self.class == other.class
  if method_description == other.method_description && @options == other.options
    true
  else
    false
  end
end

#action_aware? ⇒ Boolean

action awareness is being inherited from ancestors (in terms of nested params)

Returns:

  • (Boolean) 


225
226
227
228
229
230
231
232
233
 
# File 'lib/apipie/param_description.rb', line 225

def action_aware?
  if @options.key?(:action_aware)
    return @options[:action_aware]
  elsif @parent
    @parent.action_aware?
  else
    false
  end
end

#action_awareness ⇒ Object

makes modification that are based on the action that the param is defined for. Typical for required and allow_nil variations in create/update actions.



249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/apipie/param_description.rb', line 249

def action_awareness
  if action_aware?
    if !@options.key?(:allow_nil)
      if @required
        @allow_nil = false
      else
        @allow_nil = true
      end
    end
    if as_action != "create"
      @required = false
    end
  end
end

#as_action ⇒ Object 



235
236
237
238
239
240
241
242
243
244
 
# File 'lib/apipie/param_description.rb', line 235

def as_action
  if @options[:param_group] && @options[:param_group][:options] &&
      @options[:param_group][:options][:as]
    @options[:param_group][:options][:as].to_s
  elsif @parent
    @parent.as_action
  else
    @method_description.method
  end
end

#blank_forbidden? ⇒ Boolean

Returns:

  • (Boolean) 


130
131
132
 
# File 'lib/apipie/param_description.rb', line 130

def blank_forbidden?
  !Apipie.configuration.ignore_allow_blank_false && !allow_blank && !validator.ignore_allow_blank?
end

#concern_subst(string) ⇒ Object 



264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/apipie/param_description.rb', line 264

def concern_subst(string)
  return string if string.nil? or !from_concern?

  original = string
  string = ":#{original}" if original.is_a? Symbol

  replaced = method_description.resource.controller._apipie_perform_concern_subst(string)

  return original if replaced == string
  return replaced.to_sym if original.is_a? Symbol
  return replaced
end

#deprecated? ⇒ Boolean

Returns:

  • (Boolean) 


293
294
295
 
# File 'lib/apipie/param_description.rb', line 293

def deprecated?
  @deprecated.present?
end

#deprecation ⇒ Object 



297
298
299
300
301
302
303
304
305
306
307
308
309
310
 
# File 'lib/apipie/param_description.rb', line 297

def deprecation
  return if @deprecated.blank? || @deprecated == true

  case @deprecated
  when Hash
    Apipie::ParamDescription::Deprecation.new(
      info: @deprecated[:info],
      deprecated_in: @deprecated[:in],
      sunset_at: @deprecated[:sunset]
    )
  when String
    Apipie::ParamDescription::Deprecation.new(info: @deprecated)
  end
end

#from_concern? ⇒ Boolean

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/apipie/param_description.rb', line 105

def from_concern?
  method_description.from_concern? || @from_concern
end

#full_name ⇒ Object 



143
144
145
146
147
 
# File 'lib/apipie/param_description.rb', line 143

def full_name
  name_parts = parents_and_self.map{|p| p.name if p.show}.compact
  return name.to_s if name_parts.blank?
  return ([name_parts.first] + name_parts[1..-1].map { |n| "[#{n}]" }).join("")
end

#is_required? ⇒ Boolean

Returns:

  • (Boolean) 


281
282
283
284
285
286
287
288
289
290
291
 
# File 'lib/apipie/param_description.rb', line 281

def is_required?
  if @options.key?(:required)
    if (@options[:required] == true) || (@options[:required] == false)
      @options[:required]
    else
      Array(@options[:required]).include?(@method_description.method.to_sym)
    end
  else
    Apipie.configuration.required_by_default?
  end
end

#merge_with(other_param_desc) ⇒ Object 



186
187
188
189
190
191
192
193
 
# File 'lib/apipie/param_description.rb', line 186

def merge_with(other_param_desc)
  if self.validator && other_param_desc.validator
    self.validator.merge_with(other_param_desc.validator)
  else
    self.validator ||= other_param_desc.validator
  end
  self
end

#normalized_value(value) ⇒ Object 



109
110
111
112
113
114
115
116
117
 
# File 'lib/apipie/param_description.rb', line 109

def normalized_value(value)
  if value.is_a?(ActionController::Parameters) && !value.is_a?(Hash)
    value.to_unsafe_hash
  elsif value.is_a? Array
    value.map { |v| normalized_value (v) }
  else
    value
  end
end

#parents_and_self ⇒ Object

returns an array of all the parents: starting with the root parent ending with itself



151
152
153
154
155
156
157
158
 
# File 'lib/apipie/param_description.rb', line 151

def parents_and_self
  ret = []
  if self.parent
    ret.concat(self.parent.parents_and_self)
  end
  ret << self
  ret
end

#preformat_text(text) ⇒ Object 



277
278
279
 
# File 'lib/apipie/param_description.rb', line 277

def preformat_text(text)
  concern_subst(Apipie.markup_to_html(text || ''))
end

#process_value(value) ⇒ Object 



134
135
136
137
138
139
140
141
 
# File 'lib/apipie/param_description.rb', line 134

def process_value(value)
  value = normalized_value(value)
  if @validator.respond_to?(:process_value)
    @validator.process_value(value)
  else
    value
  end
end

#to_json(lang = nil) ⇒ Object 



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/apipie/param_description.rb', line 160

def to_json(lang = nil)
  hash = {
    name: name.to_s,
    full_name: full_name,
    description: preformat_text(Apipie.app.translate(@options[:desc], lang)),
    required: required,
    allow_nil: allow_nil,
    allow_blank: allow_blank,
    validator: validator.to_s,
    expected_type: validator.expected_type,
    metadata: metadata,
    show: show,
    validations: validations,
    deprecated: deprecated?
  }

  if deprecation.present?
    hash[:deprecation] = deprecation.to_json
  end

  if sub_params = validator.params_ordered
    hash[:params] = sub_params.map { |p| p.to_json(lang)}
  end
  hash
end

#to_s ⇒ Object 



29
30
31
 
# File 'lib/apipie/param_description.rb', line 29

def to_s
  "ParamDescription: #{method_description.id}##{name}"
end

#validate(value) ⇒ Object 



119
120
121
122
123
124
125
126
127
128
 
# File 'lib/apipie/param_description.rb', line 119

def validate(value)
  return true if allow_nil && value.nil?
  return true if allow_blank && value.blank?
  value = normalized_value(value)
  if (!allow_nil && value.nil?) || (blank_forbidden? && value.blank?) || !validator.valid?(value)
    error = validator.error
    error = ParamError.new(error) unless error.is_a? StandardError
    raise error
  end
end