Class: ApiCanon::DocumentedAction

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(action_name, controller_path, controller_name) ⇒ DocumentedAction

Returns a new instance of DocumentedAction.



6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
# File 'lib/api_canon/documented_action.rb', line 6

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

  # This is based of the rails defaults.
  @http_method = case action_name.to_s
    when "create"  then "POST"
    when "update"  then "PUT"
    when "destroy" then "DELETE"
    else "GET"
  end

  @response_codes = {}
end

Instance Attribute Details

#action_name ⇒ Object (readonly)

Returns the value of attribute action_name.



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

def action_name
  @action_name
end

#controller_name ⇒ Object (readonly)

Returns the value of attribute controller_name.



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

def controller_name
  @controller_name
end

#controller_path ⇒ Object (readonly)

Returns the value of attribute controller_path.



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

def controller_path
  @controller_path
end

#description ⇒ Object (readonly)

Returns the value of attribute description.



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

def description
  @description
end

#http_method ⇒ Object (readonly)

Returns the value of attribute http_method.



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

def http_method
  @http_method
end

#params ⇒ Object (readonly)

Returns the value of attribute params.



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

def params
  @params
end

#response_codes ⇒ Object (readonly)

Returns the value of attribute response_codes.



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

def response_codes
  @response_codes
end

#response_model_name ⇒ Object (readonly)

Returns the value of attribute response_model_name.



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

def response_model_name
  @response_model_name
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:



92
93
94
 
# File 'lib/api_canon/documented_action.rb', line 92

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:



51
52
53
 
# File 'lib/api_canon/documented_action.rb', line 51

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

#response_class(model_name) ⇒ Object

The response_class method allows you to specify name of a model describing the response

See Also:



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

def response_class(model_name)
  @response_model_name = model_name
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:



75
76
77
 
# File 'lib/api_canon/documented_action.rb', line 75

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