api_canon 0.2.4 → 0.2.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2f4993fa3f12d27e8ff54ca9ee6becafa5bb6080
+  data.tar.gz: 31e54ec37b2a8715bd0d8c31729734cc34d816ac
+SHA512:
+  metadata.gz: a851685829187972e5b14c379846f9a1fb42c587b16c52edccf46b79d67d5d61c3cd21653cb70948d07429cb1fc0ec133489462bdc41a7a074670d1613fe1880
+  data.tar.gz: 6d67a86a1019e78a56a566bdac9c5790ec63edfd958e95ee571526bd1814505cb033c23b71f247b1ee8a2841cd57630a8fc2bdaf2b27c309d65775b4e18e8d68

data/README.md

@@ -8,29 +8,101 @@ API Canon is a tool for programatically documenting Ruby on Rails APIs with exam
 ## Installation and usage
 If you're using bundler, then put this in your Gemfile:
 
-    gem 'api_canon'
-
+```ruby
+gem 'api_canon'
+```
 Then, in each controller you want to document, add the line
 
-    include ApiCanon
+```ruby
+include ApiCanon
+```
 
 ... which allows you to describe what all the actions in the controller are concerned about like this:
 
-    document_controller :as => 'optional_rename' do
-      describe "The actions here are awesome, they allow you to get a list of awesome things, and make awesome things, too!"
-    end
+```ruby
+document_controller :as => 'optional_rename' do
+  describe "The actions here are awesome, they allow you to get a list of awesome things, and make awesome things, too!"
+end
+```
 
-... and you can document all the actions you want like this:
+That is optional, but reccomended, as it gives context to users of your API.
 
-    document_method :index do
-      param :category_codes, :type => :array, :multiple => true, :example_values => Category.all(:limit => 5, :select => :code).map(&:code), :description => "Return only categories for the given category codes", :default => 'some-awesome-category-code'
-    end
+More usefully you can document all the actions you want like this:
+
+```ruby
+document_method :index do
+  param :category_codes, :type => :array, :multiple => true, :example_values => Category.all(:limit => 5, :select => :code).map(&:code), :description => "Return only categories for the given category codes", :default => 'some-awesome-category-code'
+end
+```
 
 To view the api documentation, visit the documented controller's index action with '.html' as the format.
 
 To enable the 'test' button on the generated documentation pages, you'll need to add this to your config/routes.rb file:
 
-    ApiCanon::Routes.draw(self) # Or 'map' instead of 'self' for Rails 2
+```ruby
+ApiCanon::Routes.draw(self) # Or 'map' instead of 'self' for Rails 2
+```
+
+## Examples
+
+### Standard Rails actions
+
+If you have an index action, you should render api_canon documentation when params[:format] is html. For example:
+
+```ruby
+class CategoriesController < ApplicationController
+  include ApiCanon
+
+
+  document_method :index do
+    describe "This gives you a bunch of categories."
+    param :node, :type => :string, :values => ['womens-fashion', 'mens-fashion'], :default => 'womens-fashion', :description => "Category code to start with"
+    param :depth, :type => :integer, :values => 1..4, :default => 1, :description => "Maximum depth to include child categories"
+  end
+  def index
+    # Do stuff.
+    respond_to do |format|
+      format.html { render :layout => 'api_canon'} # Defaults to api_canon index
+      format.json { render :json => @some_list_of_objects }
+    end
+  end
+end
+```
+
+### Using inherited_resources
+
+It's a little easier with InheritedResources.
+Simply include ApiCanon after you call inherit_resources.
+It will create an index action that renders the documentation if params[:format]
+is blank or :html, and defaults back to the inherited_resources index action 
+otherwise.
+
+```ruby
+class FunkyCategoriesController < ApplicationController
+  inherit_resources
+  respond_to :json, :xml
+  actions :index, :show
+
+  include ApiCanon
+
+  document_controller :as => 'Categories' do
+    describe "Categories are used for filtering products. They are hierarchical, with 4 levels. These 4 levels are known as Super-Categories, Categories, Sub-Categories and Types. Examples include \"Women's Fashion\", \"Shirts\" and so forth. They are uniquely identifiable by their category_code field."
+  end
+
+  document_method :index do
+    describe "This action returns a filtered tree of categories based on the parameters given in the request."
+    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
+
+  document_method :show do
+    describe "This action returns a tree of categories starting at the requested root node."
+    param :id, :type => :string, :example_values => Category.online.enabled.super_categories.all(:limit => 5, :select => :code).map(&:code), :description => "Category code to show, the root node for the entire tree.", :default => 'mens-fashion-accessories'
+  end
+
+  #... code to support the above documented parameters etc.
+end
+```
 
 ## Going forward
 

data/Rakefile

@@ -4,25 +4,21 @@ begin
 rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
-begin
-  require 'rdoc/task'
-rescue LoadError
-  require 'rdoc/rdoc'
-  require 'rake/rdoctask'
-  RDoc::Task = Rake::RDocTask
-end
-
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'ApiCanon'
-  rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
 
 require "bundler/gem_tasks"
 Bundler::GemHelper.install_tasks
 
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = ['lib/**/*.rb']
+    t.options = ['--markup-provider=redcarpet',
+                 '--markup=markdown',
+                 '--no-private',
+                 '--hide-void-return']
+  end
+end
+
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new

data/lib/api_canon/documented_action.rb

@@ -10,16 +10,66 @@ module ApiCanon
         :description => "The requested format of the response."
       @response_codes={}
     end
+    # The param method describes and gives examples for the parameters your
+    # API action can take.
+    # @see ApiCanon::DocumentedParam
+    # @see ApiCanon::ClassMethods#document_method
+    # @param param_name [Symbol] The name of the parameter, i.e. the param_name
+    # bit in params[param_name]
+    # @param options [Hash] This is where you describe the given parameter.
+    # 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
+    # ```
+    #
     def param(param_name, options={})
       @params[param_name] = DocumentedParam.new param_name, options
     end
-    def response_code(code, options={})
-      @response_codes[code] = options
+    # 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.
+    # @see ApiCanon::ClassMethods#document_method
+    # @param code [Integer] The response code to document, e.g. 200, 404 etc.
+    # @param desc [String] Description of what the response code means in your
+    #   case, e.g. a 422 might mean the user entered input that failed validation.
+    # ##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
+    # ```
+    def response_code(code, desc="")
+      @response_codes[code] = desc
     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.
+    # The describe method is used as a DSL method in the document_method block,
+    # Use it to describe your API action.
+    # @see ApiCanon::ClassMethods#document_method
+    # @param desc [String] The text to appear at the top of the action block in
+    # 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
+    # ```
+    #
     def describe(desc)
       @description = desc
     end

data/lib/api_canon/version.rb

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

metadata

@@ -1,36 +1,32 @@
 --- !ruby/object:Gem::Specification
 name: api_canon
 version: !ruby/object:Gem::Version
-  version: 0.2.4
-  prerelease: 
+  version: 0.2.5
 platform: ruby
 authors:
 - Cameron Walsh
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-03 00:00:00.000000000 Z
+date: 2013-05-07 00:00:00.000000000 Z
 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
@@ -38,7 +34,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -46,23 +41,50 @@ 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\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."
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    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.
 email:
 - cameron.walsh@gmail.com
 executables: []
@@ -97,27 +119,26 @@ 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: 1.8.25
+rubygems_version: 2.0.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Declarative documentation generator for APIs.
 test_files:
 - spec/spec_helper.rb
@@ -125,3 +146,4 @@ test_files:
 - spec/lib/api_canon/documented_action_spec.rb
 - spec/lib/api_canon_spec.rb
 - spec/dummy/log/test.log
+has_rdoc: