Module: ApiCanon::ClassMethods

Defined in:
lib/api_canon.rb

Instance Method Summary collapse

Instance Method Details

#document_controller(opts = {}, &block) ⇒ Object

document_controller is used to describe your controller as a whole (Your API endpoint)

Example:

document_controller as: 'Awesome Things' do
  describe "Here you can see all the awesome things, and get more details about the awesome things you're interested in."
end

Parameters:

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

    Optional, current options are: ‘as’ - An optional override for the controller name which defaults to controller_name.titleize

  • block (&block) —

    Begins the controller documentation DSL

See Also:



65
66
67
68
69
 
# File 'lib/api_canon.rb', line 65

def document_controller(opts={}, &block)
  document(opts) do |document|
    document.instance_eval &block if block_given?
  end
end

#document_method(method_name, &block) ⇒ Object

document_method is used to describe the actions in your controller (your API actions)

Example:

document_method :index do
  describe "Gives you a list of awesome things!"
  param :foo, type: 'String', default: 'bar', example_values: Foo.limit(5).pluck(:name), description: 'foo is the type of awesome required'
  param :filter_level, type: 'Integer', default: 1, values: [1,2,3,4], description: 'filter_level can only be 1, 2, 3 or 4'
end

Parameters:

  • method_name (Symbol) —

    The method to be documented

  • block (block) —

    Begins the action documentation DSL

See Also:



85
86
87
88
89
90
91
 
# File 'lib/api_canon.rb', line 85

def document_method(method_name, &block)
  document do |document|
    documented_action = ApiCanon::DocumentedAction.new method_name, controller_path, controller_name
    documented_action.instance_eval &block if block_given?
    document.add_action documented_action
  end
end

#document_model(id, &block) ⇒ Object

document_model is used to describe response object models

Example:

document_model 'Thing' do
  property :foo, type: 'string', description: 'foo is the type of awesome required', required: true
  property :filter_level, type: 'integer', description: 'filter_level can only be 1, 2, 3 or 4'
end

Parameters:

  • model_name (String) —

    The model to be documented

  • block (block) —

    Begins the model documentation DSL

See Also:



104
105
106
107
108
109
110
 
# File 'lib/api_canon.rb', line 104

def document_model(id, &block)
  document do |document|
    documented_model = ApiCanon::DocumentedModel.new id
    documented_model.instance_eval &block if block_given?
    document.add_model documented_model
  end
end