Class: ApiCanon::DocumentedAction

Inherits:
Object
  • Object
show all
Defined in:
lib/api_canon/documented_action.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(action_name) ⇒ DocumentedAction

Returns a new instance of DocumentedAction.



4
5
6
7
8
9
10
11
12
 
# File 'lib/api_canon/documented_action.rb', line 4

def initialize(action_name)
  @action_name = action_name
  @params={}
  # TODO: This should check routes to see if params[:format] is expected
  @params[:format] = DocumentedParam.new :format,
    :default => :json, :example_values => [:json, :xml], :type => :string,
    :description => "The requested format of the response."
  @response_codes={}
end

Instance Attribute Details

#action_name ⇒ Object (readonly)

Returns the value of attribute action_name.



3
4
5
 
# File 'lib/api_canon/documented_action.rb', line 3

def action_name
  @action_name
end

#description ⇒ Object (readonly)

Returns the value of attribute description.



3
4
5
 
# File 'lib/api_canon/documented_action.rb', line 3

def description
  @description
end

#params ⇒ Object (readonly)

Returns the value of attribute params.



3
4
5
 
# File 'lib/api_canon/documented_action.rb', line 3

def params
  @params
end

#response_codes ⇒ Object (readonly)

Returns the value of attribute response_codes.



3
4
5
 
# File 'lib/api_canon/documented_action.rb', line 3

def response_codes
  @response_codes
end

Instance Method Details

#describe(desc) ⇒ Object

The describe method is used as a DSL method in the document_method block, Use it to describe your API action. the generated API documentation page.

##Examples:

“‘ruby document_method :index do

describe "This action returns a filtered tree of categories based on the parameters given in the request."

end “‘

Parameters:

  • desc (String) —

    The text to appear at the top of the action block in

See Also:



73
74
75
 
# File 'lib/api_canon/documented_action.rb', line 73

def describe(desc)
  @description = desc
end

#param(param_name, options = {}) ⇒ Object

The param method describes and gives examples for the parameters your API action can take. bit in params Valid keys are:

  • default: The default value to fill in for this parameter

  • example_values: Example values to show. Use when the input is unconstrained.

  • values: Valid values to use. Use when the input is constrained.

  • type: The expected type of the value(s) of this param, e.g. :string

  • description: A friendly description of what this parameter does or is used for.

  • multiple: Can this parameter be used multiple times? I.e. Array values.

##Examples:

“‘ruby document_method :index do

param :hierarchy_level, :values => 1..4, :type => :integer, :default => 1, :description => "Maximum depth to include child categories"
param :category_codes, :type => :array, :multiple => true, :example_values => Category.online.enabled.super_categories.all(:limit => 5, :select => :code).map(&:code), :description => "Return only categories for the given category codes", :default => 'mens-fashion-accessories'

end “‘

Parameters:

  • param_name (Symbol) —

    The name of the parameter, i.e. the param_name

  • options (Hash) (defaults to: {}) —

    This is where you describe the given parameter.

See Also:



38
39
40
 
# File 'lib/api_canon/documented_action.rb', line 38

def param(param_name, options={})
  @params[param_name] = DocumentedParam.new param_name, options
end

#response_code(code, desc = "") ⇒ Object

The response_code method will be used as a DSL method in the document_method block to describe what you mean when your action returns the given response code. It currently does nothing. ##Examples:

“‘ruby document_method :index do

response_code 200, "Everything worked"
response_code 404, "Either the requested product or category could not be found"

end “‘

Parameters:

  • code (Integer) —

    The response code to document, e.g. 200, 404 etc.

  • desc (String) (defaults to: "") —

    Description of what the response code means in your case, e.g. a 422 might mean the user entered input that failed validation.

See Also:



56
57
58
 
# File 'lib/api_canon/documented_action.rb', line 56

def response_code(code, desc="")
  @response_codes[code] = desc
end