api_canon 0.2.3

checksums.yaml

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

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,52 @@
+# API Canon
+
+[![Build Status](https://travis-ci.org/cwalsh/api_canon.png?branch=master)](https://travis-ci.org/cwalsh/api_canon)
+
+## Introduction
+API Canon is a tool for programatically documenting Ruby on Rails APIs with example usage.
+
+## Installation and usage
+If you're using bundler, then put this in your Gemfile:
+
+    gem 'api_canon'
+
+Then, in each controller you want to document, add the line
+
+    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
+
+... and you can document all the actions you want like this:
+
+    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
+
+## Going forward
+
+Right now, api_canon is changing a lot.  I plan to support the following features soon:
+
+1. Response codes - describe what you mean when you send back a 200, a 201, 403 etc.
+2. Support API tokens or other authentication to allow users to edit data live, with non-GET requests.
+3. Swagger API output (optional)
+4. You will need to route the index action for each documented controller until such point as I provide an alternative means of getting at this documentation.
+
+## Contributors
+[Cameron Walsh](http://github.com/cwalsh)
+
+## Contributions
+1. Fork project
+2. Write tests, or even code as well
+3. Pull request
+4. ???
+5. Profit.

data/Rakefile

@@ -0,0 +1,31 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+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
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec

data/lib/api_canon/app/controllers/api_canon_controller.rb

@@ -0,0 +1,108 @@
+module ApiCanon
+  class ApiCanonController < ActionController::Base
+    def test
+      response = {:methods => matching_methods, :params => sanitized(params[:doco])}
+      #TODO: Put routes in here, too.
+      matching_methods.each do |m|
+        response[:curl] ||= {}
+        response[:urls] ||= {}
+        if m == :get
+          response[:curl][m] = as_curl(api_request_url)
+          response[:urls][m] = api_request_url
+        else
+          response[:curl][m] = as_curl(api_request_url_for_non_get_requests, m, non_url_parameters_for_request_generation)
+          response[:urls][m] = api_request_url_for_non_get_requests
+        end
+      end
+      render :json => response
+    end
+
+  private
+
+    def routes
+      Rails.version.starts_with?('2') ? ActionController::Routing::Routes.routes : Rails.application.routes.routes
+    end
+
+    def matching_routes
+      routes.select do |r|
+        r.requirements[:controller] == requested_controller_path.to_s &&
+          r.requirements[:action] == api_document.action_name.to_s
+      end
+    end
+
+    def as_curl(url, method=:get, params={})
+      case method
+      when :get
+        %{curl "#{url}"}
+      when :post
+        %{curl "#{url}" "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" --data "#{params.to_query}"}
+      when :put
+        %{curl "#{url}" "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" -X PUT --data "#{params.to_query}"}
+      when :delete
+        %{curl "#{url}" "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" -X DELETE --data "#{params.to_query}"}
+      else
+        "PATCH, HEAD, OPTIONS, TRACE, CONNECT are not implemented"
+      end
+    end
+
+    def matching_methods
+      #TODO: ApiDocument should define what methods it accepts, and fall back to route generation
+      if Rails.version.starts_with?('2')
+        matching_routes.map {|r| r.conditions[:method]}.uniq
+      else
+        matching_routes.map {|r| %w(GET PUT POST DELETE).select {|m| r.verb =~ m}}.flatten.uniq.map(&:downcase).map(&:to_sym)
+      end
+    end
+
+    def api_document
+      doco = ApiCanon::DocumentationStore.fetch(requested_controller_path)
+      doco.documented_actions.detect {|da| da.action_name.to_s == params[:doco][:action_name] }
+    end
+
+    def requested_controller_path
+      params[:doco][:controller_path]
+    end
+
+    def parameters_for_request_generation
+      sanitized(params[:doco]).merge({:controller => "/#{requested_controller_path}", :action => api_document.action_name})
+    end
+
+    def non_url_parameters_for_request_generation
+      parameters_for_request_generation.reject {|k,v| url_param_keys.include?(k)}
+    end
+
+    def url_param_keys
+      if Rails.version.starts_with?('2')
+        matching_routes.inject(Set.new()) {|set,r| set += r.significant_keys.map(&:to_s) }
+      else
+        matching_routes.inject(Set.new()) {|set,r| set += r.segment_keys.map(&:to_s) }
+      end
+    end
+
+    def url_parameters_for_request_generation
+      parameters_for_request_generation.slice *url_param_keys
+    end
+
+    def api_request_url_for_non_get_requests
+      unless Rails.version.starts_with?('2')
+        self.class.send(:include, Rails.application.routes.url_helpers)
+      end
+      url_for url_parameters_for_request_generation
+    end
+
+    def api_request_url
+      unless Rails.version.starts_with?('2')
+        self.class.send(:include, Rails.application.routes.url_helpers)
+      end
+      url_for parameters_for_request_generation
+    end
+
+    def sanitized(doco_params)
+      sanitized = doco_params.dup
+      sanitized.delete_if {|k,v| %w(controller controller_path action controller_name action_name).include?(k.to_s) }
+      sanitized.each {|k,v| v.reject!(&:blank?) if v.is_a? Array}
+      sanitized.delete_if {|k,v| v.blank? }
+      sanitized
+    end
+  end
+end

data/lib/api_canon/app/helpers/api_canon_view_helper.rb

@@ -0,0 +1,9 @@
+module ApiCanon
+  module ApiCanonViewHelper
+    if Rails.version.starts_with?('2')
+      def content_for?(content_partial_name)
+        instance_variable_get("@content_for_#{content_partial_name}")
+      end
+    end
+  end
+end

data/lib/api_canon/app/views/api_canon/_api_canon.html.erb

@@ -0,0 +1,71 @@
+<div class='row-fluid"'>
+  <div class='span12'>
+    <%- @api_doc ||= ::ApiCanon::DocumentationStore.fetch controller.controller_path -%>
+    <h1><%= @api_doc.display_name %></h1>
+    <p class='lead'><%= @api_doc.description %></p>
+    <%- @api_doc.documented_actions.each do |doco| -%>
+      <div class='row-fluid"'>
+        <div class='span12'>
+          <h2><%= doco.action_name.to_s.titleize %></h2>
+          <p><%= doco.description %></p>
+          <% doco_prefix = "#{@api_doc.controller_name}_#{doco.action_name}" %>
+          <% if Rails.version.starts_with?('2') %>
+            <%= render :partial => 'api_canon/rails_2_form', :locals => {:doco => doco, :doco_prefix => doco_prefix} %>
+          <% else %>
+            <%= render :partial => 'api_canon/form', :locals => {:doco => doco, :doco_prefix => doco_prefix} %>
+          <% end %>
+          <div id='<%= "#{@api_doc.controller_name}_#{doco.action_name}_results" %>' class='results'>
+            <div class='urls'></div>
+            <div class='curls'></div>
+            <div class='response'></div>
+          </div>
+        </div>
+      </div>
+    <%- end -%>
+  </div>
+</div>
+
+<script type='text/javascript'>
+  function generate_url_and_call_it(controller_name, action_name) {
+    var form = jQuery('#' + controller_name + '_' + action_name + '_form');
+    var api_url_request = form.attr('action');
+    var post_request = jQuery.post(api_url_request, form.serialize());
+    post_request.done(function(data) {
+      var urls_div = jQuery('#' + controller_name + '_' + action_name + '_results div.urls')
+      var curls_div = jQuery('#' + controller_name + '_' + action_name + '_results div.curls')
+      var response_div = jQuery('#' + controller_name + '_' + action_name + '_results div.response')
+      //urls_div.html('<p>URLs generated: </p>');
+      curls_div.html('<p>Curl requests generated: </p>');
+      //jQuery.each(data['urls'], function(key,value) {urls_div.append(key.toUpperCase() + ': <pre>' + value + '</pre>')});
+      jQuery.each(data['curl'], function(key,value) {curls_div.append(key.toUpperCase() + ': <pre>' + value + '</pre>')});
+      jQuery.each(data['urls'], function(key,value) {
+        if (key == 'get') {
+          jQuery.get(value)
+            .done(function(data,textStatus,jqXHR) {
+              response_div.removeClass('error')
+                .html('<p>Response: (' + jqXHR.status + ' ' + jqXHR.statusText + ') </p><pre></pre>')
+              if (jqXHR.getResponseHeader('Content-Type').match(/(text|application)\/json.*/)) {
+                response_div.find('pre').append(JSON.stringify(eval(data), undefined, 2))
+              } else {
+                response_div.find('pre').text(jqXHR.responseText)
+              }
+            })
+            .fail(function(jqXHR,textStatus,errorThrown) {
+              response_div.addClass('error')
+                .html('<p>Response: (' + jqXHR.status + ' ' + jqXHR.statusText + ') </p><pre></pre>')
+                response_div.find('pre').text(jqXHR.responseText)
+            })
+        }
+      });
+    });
+    return false;
+  }
+</script>
+
+<% content_for :sidebar do %>
+<ul class='nav nav-list'>
+  <% ApiCanon::DocumentationStore.instance.docos.each do |key, doco| %>
+    <li><%= link_to doco.display_name, url_for(:controller => doco.controller_path, :action => :index, :format => :html) %></li>
+  <% end %>
+</ul>
+<% end %>

data/lib/api_canon/app/views/api_canon/_form.html.erb

@@ -0,0 +1,30 @@
+<%= form_for :doco, :url => api_canon_test_path, :html => {:id => "#{@api_doc.controller_name}_#{doco.action_name}_form"}, :prefix => doco_prefix do |f| %>
+  <%= f.hidden_field :action_name, :value => doco.action_name %>
+  <%= f.hidden_field :controller_name, :value => @api_doc.controller_name %>
+  <%= f.hidden_field :controller_path, :value => @api_doc.controller_path %>
+  <%- if doco.params.any? -%>
+    <table class='table table-striped table-bordered'>
+      <thead>
+        <tr>
+          <th>Parameter</th>
+          <th>Value</th>
+          <th>Example Values</th>
+          <th>Type</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        <%- doco.params.each do |name, param| %>
+          <tr>
+            <td><%= name %></td>
+            <td><%= param.to_field(f, doco_prefix) %></td>
+            <td><%= param.example_values_field(f, doco_prefix) %></td>
+            <td><%= param.type %></td>
+            <td><%= param.description %></td>
+          </tr>
+        <%- end -%>
+      </tbody>
+    </table>
+  <%- end -%>
+  <%= f.submit "Test", :onclick => "generate_url_and_call_it('#{@api_doc.controller_name}', '#{doco.action_name}'); return false;", :class => 'btn' %>
+<%- end -%>

data/lib/api_canon/app/views/api_canon/_rails_2_form.html.erb

@@ -0,0 +1,30 @@
+<% form_for :doco, :url => api_canon_test_path, :html => {:id => "#{@api_doc.controller_name}_#{doco.action_name}_form"} do |f| %>
+  <%= f.hidden_field :action_name, :value => doco.action_name %>
+  <%= f.hidden_field :controller_name, :value => @api_doc.controller_name %>
+  <%= f.hidden_field :controller_path, :value => @api_doc.controller_path %>
+  <%- if doco.params.any? -%>
+    <table class='table table-striped table-bordered'>
+      <thead>
+        <tr>
+          <th>Parameter</th>
+          <th>Value</th>
+          <th>Example Values</th>
+          <th>Type</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        <%- doco.params.each do |name, param| %>
+          <tr>
+            <td><%= name %></td>
+            <td><%= param.to_field(f, doco_prefix) %></td>
+            <td><%= param.example_values_field(f, doco_prefix) %></td>
+            <td><%= param.type %></td>
+            <td><%= param.description %></td>
+          </tr>
+        <%- end -%>
+      </tbody>
+    </table>
+  <%- end -%>
+  <%= f.submit "Test", :onclick => "generate_url_and_call_it('#{@api_doc.controller_name}', '#{doco.action_name}'); return false;", :class => 'btn' %>
+<% end %>

data/lib/api_canon/app/views/api_canon/api_canon.html.erb

@@ -0,0 +1 @@
+<%= render :partial => 'api_canon/api_canon' %>

data/lib/api_canon/app/views/application/index.html.erb

@@ -0,0 +1 @@
+<%= render :partial => 'api_canon/api_canon' %>

data/lib/api_canon/app/views/layouts/api_canon.html.erb

@@ -0,0 +1,67 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <%= yield :meta %>
+    <title><%= content_for?(:title) ? yield(:title) : "API Documentation" %></title>
+    <%= csrf_meta_tag %>
+
+    <link href="//netdna.bootstrapcdn.com/twitter-bootstrap/2.3.1/css/bootstrap-combined.min.css" rel="stylesheet">
+    <style>
+      body {
+        padding-top: 60px; /* 60px to make the container go all the way to the bottom of the topbar */
+      }
+    </style>
+    <%= stylesheet_link_tag "application", :media => "all" %>
+
+    <!-- HTML5 shim, for IE6-8 support of HTML5 elements -->
+    <!--[if lt IE 9]>
+      <script src="http://html5shiv.googlecode.com/svn/trunk/html5.js">
+    <![endif]-->
+
+    <!-- Fav and touch icons -->
+    <%# TODO: Implement these %>
+    <link rel="apple-touch-icon-precomposed" sizes="144x144" href="/images/ico/apple-touch-icon-144-precomposed.png">
+    <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/images/ico/apple-touch-icon-114-precomposed.png">
+      <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/images/ico/apple-touch-icon-72-precomposed.png">
+                    <link rel="apple-touch-icon-precomposed" href="/images/ico/apple-touch-icon-57-precomposed.png">
+                                   <link rel="shortcut icon" href="/images/ico/favicon.png">
+  </head>
+
+  <body>
+
+    <div class="container-fluid">
+      <div class="row-fluid">
+        <% if content_for? :sidebar %>
+          <div class="span3">
+            <div class="well sidebar-nav">
+              <%= yield :sidebar %>
+            </div><!--/.well -->
+          </div><!--/span-->
+        <% end %>
+        <div class="span<%= content_for?(:sidebar) ? 8 : 11 %>">
+          <% if content_for?(:hero) %>
+            <div class="hero-unit">
+              <%= yield :hero %>
+            </div>
+          <% end %>
+          <%= yield %>
+        </div><!--/span-->
+      </div><!--/row-->
+
+      <footer>
+        <%= yield :footer %>
+      </footer>
+
+    </div>
+
+    <!-- Javascript
+    ================================================== -->
+    <script src="http://code.jquery.com/jquery-1.9.1.min.js"></script>
+    <script src="//netdna.bootstrapcdn.com/twitter-bootstrap/2.3.1/js/bootstrap.min.js"></script>
+    <%= javascript_include_tag "application" %>
+
+  </body>
+</html>
+

data/lib/api_canon/app.rb

@@ -0,0 +1 @@
+require 'api_canon/app/controllers/api_canon_controller'

data/lib/api_canon/document.rb

@@ -0,0 +1,29 @@
+module ApiCanon
+  class Document
+    attr_reader :description, :controller_path, :controller_name
+    attr_accessor :documented_actions
+    def initialize(controller_path, controller_name, opts={})
+      @controller_path = controller_path
+      @controller_name = controller_name
+      self.display_name = opts[:as]
+      @documented_actions = []
+    end
+    def describe(desc)
+      @description = desc
+    end
+    def display_name
+      @display_name || @controller_name.titleize
+    end
+    def display_name=(dn)
+      if dn.nil?
+        @display_name = nil
+      else
+        dn = dn.to_s
+        @display_name = (dn =~ /\A([a-z]*|[A-Z]*)\Z/ ? dn.titleize : dn)
+      end
+    end
+    def add_action(documented_action)
+      @documented_actions << documented_action unless @documented_actions.map(&:action_name).include?(documented_action.action_name)
+    end
+  end
+end

data/lib/api_canon/documentation_store.rb

@@ -0,0 +1,23 @@
+module ApiCanon
+  # Replace this at the earliest possible opportunity
+  # with something that stores stuff in Redis or something
+  class DocumentationStore
+    include Singleton
+    def store cont_doco
+      @docos ||= {}
+      @docos[cont_doco.controller_path] = cont_doco
+    end
+    def docos
+      @docos ||= {}
+    end
+    def self.docos
+      self.instance.docos
+    end
+    def self.store cont_doco
+      self.instance.store cont_doco
+    end
+    def self.fetch controller_path
+      self.instance.docos[controller_path]
+    end
+  end
+end

data/lib/api_canon/documented_action.rb

@@ -0,0 +1,23 @@
+module ApiCanon
+  class DocumentedAction
+    attr_reader :params, :response_codes, :description, :action_name
+    def initialize(action_name)
+      @action_name = action_name
+      @params={}
+      # TODO: This should check routes to see if params[:format] is expected
+      @params[:format] = DocumentedParam.new :format,
+        :default => :json, :example_values => [:json, :xml], :type => :string,
+        :description => "The requested format of the response."
+      @response_codes={}
+    end
+    def param(param_name, options={})
+      @params[param_name] = DocumentedParam.new param_name, options
+    end
+    def response_code(code, options={})
+      @response_codes[code] = options
+    end
+    def describe(desc)
+      @description = desc
+    end
+  end
+end

data/lib/api_canon/documented_param.rb

@@ -0,0 +1,40 @@
+module ApiCanon
+  class DocumentedParam
+    attr_accessor :name, :values, :type, :default, :description, :example_values
+    attr_writer :multiple
+    include ActionView::Helpers
+    def values_for_example
+      example_values || values || ""
+    end
+    def multiple?
+      !!@multiple
+    end
+    def initialize(name, opts={})
+      @name = name
+      opts.each {|k,v| self.send("#{k}=", v) }
+    end
+    def form_values
+      values.presence || example_values.presence
+    end
+    def to_field(f, doco_prefix)
+      # TODO: This doco_prefix thing sucks. Get rid of it.
+      if type == :array
+        f.select name, form_values, {:selected => default, :include_blank => true}, {:multiple => multiple?, :class => 'input-block-level', :id => "#{doco_prefix}_#{name}"}
+      elsif type == :boolean
+        f.select name, [true,false], {:selected => default, :include_blank => true}, :class => 'input-block-level', :id => "#{doco_prefix}_#{name}"
+      else
+        f.text_field name, :value => default, :class => 'input-block-level', :id => "#{doco_prefix}_#{name}"
+      end
+    end
+    def example_values_field(f, doco_prefix)
+      if values_for_example.is_a?(Array)
+        if type != :array
+          select_tag :example_value, options_for_select([""] + values_for_example, default), :class => 'input-block-level',
+            :onchange => "jQuery('##{doco_prefix}_#{name}').val(this.value)", :id => "#{doco_prefix}_#{name}_example"
+        end
+      else
+        values_for_example
+      end
+    end
+  end
+end

data/lib/api_canon/routes.rb

@@ -0,0 +1,12 @@
+module ApiCanon
+  module Routes
+    def self.draw(map, options={})
+      route_opts = {:as => 'api_canon_test', :controller => 'api_canon/api_canon', :action => 'test'}.merge options
+      if Rails.version.starts_with?('2')
+        map.api_canon_test 'api_canon/test', route_opts
+      else
+        map.match 'api_canon/test', route_opts
+      end
+    end
+  end
+end

data/lib/api_canon/version.rb

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

data/lib/api_canon.rb

@@ -0,0 +1,54 @@
+require 'api_canon/routes'
+require 'api_canon/version'
+require 'api_canon/app'
+require 'api_canon/document'
+require 'api_canon/documented_action'
+require 'api_canon/documented_param'
+require 'api_canon/documentation_store'
+
+module ApiCanon
+
+  def self.included(base)
+    base.extend(ClassMethods)
+    base.class_eval do
+      append_view_path File.join(File.dirname(__FILE__),'api_canon','app','views')
+      require 'api_canon/app/helpers/api_canon_view_helper'
+      helper ApiCanon::ApiCanonViewHelper
+    end
+  end
+
+  def api_canon_docs
+    @api_doc = DocumentationStore.fetch controller_path
+    respond_to do |format|
+      format.html { render 'api_canon/api_canon', :layout => 'layouts/api_canon' }
+    end
+  end
+
+  def index
+    if params[:format].blank? || params[:format] == 'html'
+      api_canon_docs
+    else
+      super
+    end
+  end
+
+  module ClassMethods
+  protected
+    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
+    def document_method(method_name,&block)
+      document = DocumentationStore.fetch controller_path
+      document ||= Document.new controller_path, controller_name
+      documented_action = ApiCanon::DocumentedAction.new method_name
+      documented_action.instance_eval &block
+      document.add_action documented_action
+      DocumentationStore.store document
+    end
+  end
+
+
+end

data/lib/tasks/api_canon_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :api_canon do
+#   # Task goes here
+# end

data/spec/lib/api_canon/documented_action_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper'
+describe ApiCanon::DocumentedAction do
+
+  let(:document) {ApiCanon::DocumentedAction.new :index}
+  let(:description) {'ID is the unique identifier of the object'}
+  subject { document }
+  its(:action_name) { should == :index }
+  it "Should document the 'format' param by default" do
+    expect(document.params[:format]).to be_a ApiCanon::DocumentedParam
+    expect(document.params[:format].example_values). to eq [:json, :xml]
+    expect(document.params[:format].default).to eq :json
+  end
+  describe :param do
+    it "documents the named param" do
+      document.param :id, :default => 1, :description => description, :type => :integer
+      expect(document.params[:id]).to be_a ApiCanon::DocumentedParam
+      expect(document.params[:id].default).to eq 1
+      expect(document.params[:id].description).to eq description
+    end
+  end
+  describe :response_code do
+    it "describes the response codes the user can expect to see" do
+      document.response_code 200
+      pending "Need to create objects to deal with this similarly to DocumentedParam"
+    end
+  end
+  describe :description do
+    let(:description) {"This action lists a bunch of things"}
+    it "describes what the controller action is for" do
+      document.describe description
+      expect(document.description).to eq description
+    end
+  end
+
+end

data/spec/lib/api_canon/documented_param_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+describe ApiCanon::DocumentedParam do
+  let(:example_values) { [:json, :xml] }
+  let(:doc_opts) do
+    {:type => 'string', :default => :json, :example_values => example_values}
+  end
+  let(:fake_form) { mock :form }
+  let(:doco_prefix) { 'foo' }
+  let(:documented_param) {ApiCanon::DocumentedParam.new :format, doc_opts}
+  subject { documented_param }
+  its(:name) { should eq :format }
+  its(:type) { should eq 'string' }
+  its(:default) { should eq :json }
+  its(:form_values) { should eq example_values }
+  its(:multiple?) { should eq false }
+  describe :to_field do
+    context "string-type params" do
+      it "Creates a text field" do
+        fake_form.should_receive :text_field
+        documented_param.to_field fake_form, doco_prefix
+      end
+    end
+    context "array-type params" do
+      before(:each) {documented_param.type = :array}
+      it "Creates a select field" do
+        fake_form.should_receive(:select).with :format, [:json, :xml], hash_including({:include_blank => true}), hash_including({:id => 'foo_format'})
+        documented_param.to_field fake_form, doco_prefix
+      end
+    end
+    context "boolean-type params" do
+      before(:each) {documented_param.type = :boolean}
+      it "Creates a select field with true and false values" do
+        fake_form.should_receive(:select).with :format, [true, false], hash_including({:include_blank => true}), hash_including({:id => 'foo_format'})
+        documented_param.to_field fake_form, doco_prefix
+      end
+    end
+  end
+  describe :example_values_field do
+    context "array of example values" do
+      it "Creates a select field" do
+        documented_param.should_receive(:select_tag)
+        documented_param.example_values_field fake_form, doco_prefix
+      end
+      it "does nothing with array-value fields" do
+        documented_param.type = :array
+        expect(documented_param.example_values_field(fake_form, doco_prefix)).to eq nil
+      end
+      it "returns the example values otherwise" do
+        documented_param.example_values = 'foo'
+        expect(documented_param.example_values_field(fake_form, doco_prefix)).to eq 'foo'
+      end
+    end
+  end
+end

data/spec/lib/api_canon_spec.rb

@@ -0,0 +1,43 @@
+require 'spec_helper'
+
+describe ApiCanon do
+  let(:fake_controller) do
+    class FakeController < ActionController::Base
+      include ApiCanon
+    end
+  end
+  describe 'including' do
+    it "adds class methods to the controller" do
+      expect(fake_controller.methods.map(&:to_s)).to include('document_method')
+    end
+    it "adds instance methods to the controller" do
+      expect(fake_controller.new.methods.map(&:to_s)).to include('api_canon_docs')
+      expect(fake_controller.new.methods.map(&:to_s)).to include('index')
+    end
+  end
+
+  describe "document_method" do
+    let(:api_document) { mock :api_document }
+    context "without a current controller doc" do
+      it "creates and stores a new ApiCanon::Document and adds the documented action" do
+        ApiCanon::Document.should_receive(:new).with('fake', 'fake').and_return(api_document)
+        ApiCanon::DocumentationStore.instance.should_receive(:store).with(api_document)
+        api_document.should_receive :add_action
+        fake_controller.send(:document_method, :index, &(Proc.new {}))
+      end
+    end
+    context "with a current controller doc" do
+      before(:each) do
+        fake_controller.send(:document_controller, &(Proc.new {}))
+      end
+      it "adds a documented action to the current controller doc" do
+        expect {
+          fake_controller.send(:document_method, :index, &(Proc.new {}))
+        }.to change {
+          ApiCanon::DocumentationStore.fetch('fake').documented_actions.count
+        }.by(1)
+      end
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+# Configure Rails Environment
+ENV["RAILS_ENV"] = "test"
+require 'rails'
+require 'singleton'
+require 'action_controller'
+require 'api_canon'
+# Load support files
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |f| require f }
+

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: api_canon
+version: !ruby/object:Gem::Version
+  version: 0.2.3
+platform: ruby
+authors:
+- Cameron Walsh
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 2.3.17
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 2.3.17
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  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: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/api_canon/documented_param.rb
+- lib/api_canon/version.rb
+- lib/api_canon/documented_action.rb
+- lib/api_canon/documentation_store.rb
+- lib/api_canon/app/views/api_canon/api_canon.html.erb
+- lib/api_canon/app/views/api_canon/_form.html.erb
+- lib/api_canon/app/views/api_canon/_api_canon.html.erb
+- lib/api_canon/app/views/api_canon/_rails_2_form.html.erb
+- lib/api_canon/app/views/application/index.html.erb
+- lib/api_canon/app/views/layouts/api_canon.html.erb
+- lib/api_canon/app/controllers/api_canon_controller.rb
+- lib/api_canon/app/helpers/api_canon_view_helper.rb
+- lib/api_canon/app.rb
+- lib/api_canon/document.rb
+- lib/api_canon/routes.rb
+- lib/tasks/api_canon_tasks.rake
+- lib/api_canon.rb
+- MIT-LICENSE
+- Rakefile
+- README.md
+- spec/spec_helper.rb
+- spec/lib/api_canon/documented_param_spec.rb
+- spec/lib/api_canon/documented_action_spec.rb
+- spec/lib/api_canon_spec.rb
+- spec/dummy/log/test.log
+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
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Declarative documentation generator for APIs.
+test_files:
+- spec/spec_helper.rb
+- spec/lib/api_canon/documented_param_spec.rb
+- spec/lib/api_canon/documented_action_spec.rb
+- spec/lib/api_canon_spec.rb
+- spec/dummy/log/test.log