api_canon 0.2.3 → 0.2.4

data/lib/api_canon.rb

@@ -24,6 +24,9 @@ module ApiCanon
     end
   end
 
+  # When this module is included, your index method is overwritten with this one,
+  # which renders the ApiCanon documentation if params[:format] is html, and defaults
+  # to the existing method otherwise.
   def index
     if params[:format].blank? || params[:format] == 'html'
       api_canon_docs
@@ -33,13 +36,38 @@ module ApiCanon
   end
 
   module ClassMethods
-  protected
+    # 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
     def document_controller(opts={}, &block)
       document = DocumentationStore.fetch controller_path
       document ||= Document.new controller_path, controller_name, opts
       document.instance_eval &block
       DocumentationStore.store document
     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
     def document_method(method_name,&block)
       document = DocumentationStore.fetch controller_path
       document ||= Document.new controller_path, controller_name

data/lib/api_canon/document.rb

@@ -8,6 +8,10 @@ module ApiCanon
       self.display_name = opts[:as]
       @documented_actions = []
     end
+    # The describe method is used as a DSL method in the document_controller block,
+    # use it to describe your API endpoint as a whole.
+    # @see ApiCanon::ClassMethods#document_controller
+    # @param desc [String] The text to appear at the top of your API endpoint documentation page.
     def describe(desc)
       @description = desc
     end

data/lib/api_canon/documentation_store.rb

@@ -1,3 +1,4 @@
+require 'singleton'
 module ApiCanon
   # Replace this at the earliest possible opportunity
   # with something that stores stuff in Redis or something

data/lib/api_canon/documented_action.rb

@@ -16,6 +16,10 @@ module ApiCanon
     def response_code(code, options={})
       @response_codes[code] = options
     end
+    # The describe method is used as a DSL method in the document_action block,
+    # use it to describe your API endpoint as a whole.
+    # @see ApiCanon::ClassMethods#document_action
+    # @param desc [String] The text to appear at the top of your API endpoint documentation page.
     def describe(desc)
       @description = desc
     end

data/lib/api_canon/version.rb

@@ -1,3 +1,3 @@
 module ApiCanon
-  VERSION = '0.2.3'
+  VERSION = '0.2.4'
 end

metadata

@@ -1,7 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: api_canon
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
+  prerelease: 
 platform: ruby
 authors:
 - Cameron Walsh
@@ -13,20 +14,23 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 2.3.17
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 2.3.17
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -34,6 +38,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -41,22 +46,23 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: |-
-  api_canon is a declarative documentation generator
-                         for APIs. Declare the parameters and response codes,
-                         describe them, and give some example values. api_canon
-                         handles the rest for you.
+description: ! "api_canon is a declarative documentation generator\n                       for
+  APIs. Declare the parameters and response codes,\n                       describe
+  them, and give some example values. api_canon\n                       handles the
+  rest for you."
 email:
 - cameron.walsh@gmail.com
 executables: []
@@ -91,26 +97,27 @@ files:
 homepage: http://github.com/cwalsh/api_canon
 licenses:
 - MIT
-metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 1.8.25
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: Declarative documentation generator for APIs.
 test_files:
 - spec/spec_helper.rb

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA1:
-  metadata.gz: 1fe88b5c318faea3491eed88a7679b503758363b
-  data.tar.gz: e07f1ce662c6c7de16941a0bc17372f2e5c5e321
-SHA512:
-  metadata.gz: b3ee1f26f4b745e920784701636eef94c250c2cc31a872d2eed3415300c254d48042bac7755440908373c436a05d5e0685f5215f79c40d1d251732673d74dd90
-  data.tar.gz: 898a5e1b441f4783c9f6d2f5104cc3031f72fe6674e643ea200063196492f7d2cd9461dbf720583902b2358a5edfc55ca8602ff0774025deebe09daab67852d6