module ApiCanon::ClassMethods

Public Instance Methods

document_controller(opts={}, &block) click to toggle source

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

@param opts [Hash] Optional, current options are:

'as' - An optional override for the controller name which defaults to controller_name.titleize

@param block [&block] Begins the controller documentation DSL @see ApiCanon::Document#describe

# 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) click to toggle source

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

@param method_name [Symbol] The method to be documented @param block [block] Begins the action documentation DSL @see ApiCanon::DocumentedAction#describe @see ApiCanon::DocumentedAction#param @see ApiCanon::DocumentedAction#response_code

# 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) click to toggle source

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

@param model_name [String] The model to be documented @param block [block] Begins the model documentation DSL @see ApiCanon::DocumentedModel#property

# 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

Private Instance Methods

document(opts={}, &block) click to toggle source
# File lib/api_canon.rb, line 114
def document(opts={}, &block)
  document = DocumentationStore.fetch controller_path
  document ||= Document.new controller_path, controller_name, opts
  block.call document if block_given?
  DocumentationStore.store document
end