Feature comments

api_taster.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'jquery-rails'
   s.add_dependency 'sass-rails'
   s.add_dependency 'bootstrap-sass', '~> 2.0.3'
+  s.add_dependency 'redcarpet'
 
   s.add_development_dependency 'rake'
   s.add_development_dependency 'simplecov'

app/controllers/api_taster/routes_controller.rb

@@ -11,6 +11,7 @@ def index
     def show
       @route  = Route.find(params[:id])
       @params = Route.params_for(@route)
+      @comment = Route.comment_for(params[:id])
     end
 
     def missing_definitions

app/helpers/api_taster/application_helper.rb

@@ -1,4 +1,10 @@
+require 'redcarpet'
+
 module ApiTaster
   module ApplicationHelper
+    def markdown(text)
+      markdown_renderer ||= Redcarpet::Markdown.new(Redcarpet::Render::HTML)
+      markdown_renderer.render(text).html_safe
+    end
   end
 end

app/views/api_taster/routes/show.html.erb

@@ -8,6 +8,13 @@
 <% if @params.is_a?(Hash) && @params.has_key?(:undefined) %>
   <%= render 'undefined_route', :route => @params[:undefined] %>
 <% else %>
+
+  <% if @comment %>
+    <div class="well">
+      <%= markdown @comment %>
+    </div>
+  <% end %>
+
   <% @params.each do |param| %>
     <%= form_tag @route[:path], :method => @route[:verb], :class => 'well form-horizontal', :remote => true do %>
 

lib/api_taster/mapper.rb

@@ -1,5 +1,7 @@
 module ApiTaster
   class Mapper
+    cattr_accessor :last_desc
+
     class << self
       def get(path, params = {})
         map_method(:get, path, params)
@@ -17,6 +19,10 @@ def delete(path, params = {})
         map_method(:delete, path, params)
       end
 
+      def desc(text)
+        self.last_desc = text
+      end
+
       private
 
       def map_method(method, path, params)
@@ -31,6 +37,10 @@ def map_method(method, path, params)
         else
           Route.supplied_params[route[:id]] ||= []
           Route.supplied_params[route[:id]] << ApiTaster.global_params.merge(params)
+          unless last_desc.nil?
+            Route.comments[route[:id]] = last_desc
+            self.last_desc = nil
+          end
         end
       end
     end

lib/api_taster/route.rb

@@ -5,13 +5,15 @@ class Route
     cattr_accessor :mappings
     cattr_accessor :supplied_params
     cattr_accessor :obsolete_definitions
+    cattr_accessor :comments
 
     class << self
 
       def map_routes
         self.route_set            = Rails.application.routes
         self.supplied_params      = {}
         self.obsolete_definitions = []
+        self.comments             = []
 
         normalise_routes!
 
@@ -71,6 +73,10 @@ def params_for(route)
         supplied_params[route[:id]].collect { |input| split_input(input, route) }
       end
 
+      def comment_for(id)
+        self.comments[id.to_i]
+      end
+
       def defined_definitions
         routes.reject { |route| undefined_route?(route) }
       end

spec/mapper_spec.rb

@@ -46,6 +46,7 @@ module ApiTaster
 
     before(:all) do
       ApiTaster.routes do
+        desc "Dummy user ID"
         get '/dummy_users/:id', :id => 1
         post '/dummy_users'
         post '/dummy_users', { :hello => 'world' }
@@ -79,5 +80,17 @@ module ApiTaster
 
       Route.supplied_params[route[:id]].should == [{ :id => 3 }]
     end
+
+    it "describes a route" do
+      route = Route.find_by_verb_and_path(:get, '/dummy_users/:id')
+
+      Route.comment_for(route[:id]).should == "Dummy user ID"
+    end
+
+    it "don't describe a route" do
+      route = Route.find_by_verb_and_path(:post, '/dummy_users')
+
+      Route.comment_for(route[:id]).should be_nil
+    end
   end
 end

spec/route_spec.rb

@@ -96,6 +96,12 @@ module ApiTaster
       end
     end
 
+    it "#comment_for" do
+      markdown_comment = "Heading\n=======\n * List item 1\n * List item 2"
+      Route.comments[42] = markdown_comment
+      Route.comment_for(42).should eq(markdown)
+    end
+
     it "#missing_definitions and #defined_definitions" do
       routes = ActionDispatch::Routing::RouteSet.new
       routes.draw do