Module: Apipie::DSL::Common

Included in:
Concern, Controller, ResourceDescriptionDsl
Defined in:
lib/apipie/dsl_definition.rb

Instance Method Summary collapse

Instance Method Details

#_apipie_define_validators(description) ⇒ Object 



233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
 
# File 'lib/apipie/dsl_definition.rb', line 233

def _apipie_define_validators(description)

  # [re]define method only if validation is turned on
  if description && (Apipie.configuration.validate == true ||
                     Apipie.configuration.validate == :implicitly ||
                     Apipie.configuration.validate == :explicitly)

    _apipie_save_method_params(description.method, description.params)

    unless instance_methods.include?(:apipie_validations)
      define_method(:apipie_validations) do
        method_params = self.class._apipie_get_method_params(action_name)

        if Apipie.configuration.validate_presence?
          method_params.each do |_, param|
            # check if required parameters are present
            raise ParamMissing.new(param) if param.required && !params.has_key?(param.name)
          end
        end

        if Apipie.configuration.validate_value?
          method_params.each do |_, param|
            # params validations
            param.validate(params[:"#{param.name}"]) if params.has_key?(param.name)
          end
        end

        # Only allow params passed in that are defined keys in the api
        # Auto skip the default params (format, controller, action)
        if Apipie.configuration.validate_key?
          params.reject{|k,_| %w[format controller action].include?(k.to_s) }.each_pair do |param, _|
            # params allowed
            raise UnknownParam.new(param) if method_params.select {|_,p| p.name.to_s == param.to_s}.empty?
          end
        end

        if Apipie.configuration.process_value?
          @api_params ||= {}
          method_params.each do |_, param|
            # params processing
            @api_params[param.as] = param.process_value(params[:"#{param.name}"]) if params.has_key?(param.name)
          end
        end
      end
    end

    if (Apipie.configuration.validate == :implicitly || Apipie.configuration.validate == true)
      old_method = instance_method(description.method)

      define_method(description.method) do |*args|
        apipie_validations

        # run the original method code
        old_method.bind(self).call(*args)
      end
    end

  end
end

#_apipie_get_method_params(method) ⇒ Object 



298
299
300
 
# File 'lib/apipie/dsl_definition.rb', line 298

def _apipie_get_method_params(method)
  @method_params[method]
end

#_apipie_save_method_params(method, params) ⇒ Object 



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

def _apipie_save_method_params(method, params)
  @method_params ||= {}
  @method_params[method] = params
end

#api_versions(*versions) ⇒ Object Also known as: api_version 



160
161
162
 
# File 'lib/apipie/dsl_definition.rb', line 160

def api_versions(*versions)
  _apipie_dsl_data[:api_versions].concat(versions)
end

#desc(description) ⇒ Object Also known as: description, full_description

Describe the next method.

Example:

desc "print hello world"
def hello_world
  puts "hello world"
end



173
174
175
176
177
178
179
 
# File 'lib/apipie/dsl_definition.rb', line 173

def desc(description) #:doc:
  return unless Apipie.active_dsl?
  if _apipie_dsl_data[:description]
    raise "Double method description."
  end
  _apipie_dsl_data[:description] = description
end

#document(path) ⇒ Object

describe next method with document in given path in convension, these doc located under “#Rails.root/doc” Example: document “hello_world.md” def hello_world

puts "hello world"

end



190
191
192
193
 
# File 'lib/apipie/dsl_definition.rb', line 190

def document path
  content = File.open(File.join(Rails.root,  Apipie.configuration.doc_path, path)).read
  desc content
end

#error(code_or_options, desc = nil, options = {}) ⇒ Object

Describe possible errors

Example:

error :desc => "speaker is sleeping", :code => 500, :meta => [:some, :more, :data]
error 500, "speaker is sleeping"
def hello_world
  return 500 if self.speaker.sleeping?
  puts "hello world"
end



221
222
223
224
 
# File 'lib/apipie/dsl_definition.rb', line 221

def error(code_or_options, desc=nil, options={}) #:doc:
  return unless Apipie.active_dsl?
  _apipie_dsl_data[:errors] << [code_or_options, desc, options]
end

#formats(formats) ⇒ Object

Describe available request/response formats

formats ['json', 'jsonp', 'xml']



198
199
200
201
 
# File 'lib/apipie/dsl_definition.rb', line 198

def formats(formats) #:doc:
  return unless Apipie.active_dsl?
  _apipie_dsl_data[:formats] = formats
end

#header(header_name, description, options = {}) ⇒ Object

Describe request header.

Headers can't be validated with config.validate_presence = true

Example:

header 'ClientId', "client-id"
def show
  render :text => headers['HTTP_CLIENT_ID']
end



311
312
313
314
315
316
317
318
 
# File 'lib/apipie/dsl_definition.rb', line 311

def header(header_name, description, options = {}) #:doc
  return unless Apipie.active_dsl?
  _apipie_dsl_data[:headers] << {
    name: header_name,
    description: description,
    options: options
  }
end

#meta(meta) ⇒ Object

Describe additional metadata

meta :author => { :name => 'John', :surname => 'Doe' }



206
207
208
 
# File 'lib/apipie/dsl_definition.rb', line 206

def meta(meta) #:doc:
  _apipie_dsl_data[:meta] = meta
end

#tags(*args) ⇒ Object

Add tags to resources and actions group operations together.



227
228
229
230
231
 
# File 'lib/apipie/dsl_definition.rb', line 227

def tags(*args)
  return unless Apipie.active_dsl?
  tags = args.length == 1 ? args.first : args
  _apipie_dsl_data[:tag_list] += tags
end