module ApiCanon::ClassMethods
Public Instance Methods
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
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
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
# 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