Declare an api.
Example:
api :GET, "/resource_route", "short description",
# File lib/apipie/dsl_definition.rb, line 29 def api(method, path, desc = nil) #:doc: return unless Apipie.active_dsl? Apipie.add_method_description_args(method, path, desc) end
Describe the next method.
Example:
desc "print hello world" def hello_world puts "hello world" end
# File lib/apipie/dsl_definition.rb, line 42 def desc(description) #:doc: return unless Apipie.active_dsl? if Apipie.last_description raise "Double method description." end Apipie.last_description = description end
Describe possible errors
Example:
error :desc => "speaker is sleeping", :code => 500 error 500, "speaker is sleeping" def hello_world return 500 if self.speaker.sleeping? puts "hello world" end
# File lib/apipie/dsl_definition.rb, line 87 def error(*args) #:doc: return unless Apipie.active_dsl? Apipie.last_errors << Apipie::ErrorDescription.new(args) end
Show some example of what does the described method return.
# File lib/apipie/dsl_definition.rb, line 64 def example(example) #:doc: return unless Apipie.active_dsl? Apipie.add_example(example) end
Describe available request/response formats
formats ['json', 'jsonp', 'xml']
# File lib/apipie/dsl_definition.rb, line 72 def formats(formats) #:doc: return unless Apipie.active_dsl? Apipie.last_formats = formats end
create method api and redefine newly added method
# File lib/apipie/dsl_definition.rb, line 106 def method_added(method_name) #:doc: super return unless Apipie.active_dsl? return unless Apipie.apipie_provided? # remove method description if exists and create new one Apipie.remove_method_description(self, method_name) description = Apipie.define_method_description(self, method_name) # redefine method only if validation is turned on if Apipie.configuration.validate == true old_method = instance_method(method_name) define_method(method_name) do |*args| if Apipie.configuration.validate == true description.params.each do |_, param| # check if required parameters are present if param.required && !params.has_key?(param.name) raise ParamMissing.new(param.name) end # params validations if params.has_key?(param.name) param.validate(params[:"#{param.name}"]) end end end # run the original method code old_method.bind(self).call(*args) end end end
Describe method’s parameter
Example:
param :greeting, String, :desc => "arbitrary text", :required => true def hello_world(greeting) puts greeting end
# File lib/apipie/dsl_definition.rb, line 100 def param(param_name, validator, desc_or_options = nil, options = {}, &block) #:doc: return unless Apipie.active_dsl? Apipie.last_params << Apipie::ParamDescription.new(param_name, validator, desc_or_options, options, &block) end
Describe whole resource
Example: api :desc => “Show user profile”, :path => “/users/”, :version => ‘1.0 - 3.4.2012’ param :id, Fixnum, :desc => “User ID”, :required => true desc <<-EOS
Long description...
EOS
# File lib/apipie/dsl_definition.rb, line 18 def resource_description(options = {}, &block) #:doc: return unless Apipie.active_dsl? Apipie.remove_resource_description(self) Apipie.define_resource_description(self, &block) if block_given? end