From 38650aba13105b592a6e89963f38af9c0c73848d Mon Sep 17 00:00:00 2001
From: Emil Melnikov <emilmelnikov@gmail.com>
Date: Mon, 23 Jul 2012 19:05:59 +0400
Subject: [PATCH 1/2] Add comments to endpoints

---
 api_taster.gemspec                              |  1 +
 app/controllers/api_taster/routes_controller.rb |  1 +
 app/helpers/api_taster/application_helper.rb    |  6 ++++++
 app/views/api_taster/routes/show.html.erb       |  7 +++++++
 lib/api_taster/mapper.rb                        | 10 ++++++++++
 lib/api_taster/route.rb                         |  6 ++++++
 6 files changed, 31 insertions(+)

diff --git a/api_taster.gemspec b/api_taster.gemspec
index 00820b2..e8d445d 100644
--- a/api_taster.gemspec
+++ b/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'
diff --git a/app/controllers/api_taster/routes_controller.rb b/app/controllers/api_taster/routes_controller.rb
index 47d8dcd..f17e8ae 100644
--- a/app/controllers/api_taster/routes_controller.rb
+++ b/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
diff --git a/app/helpers/api_taster/application_helper.rb b/app/helpers/api_taster/application_helper.rb
index f7de1c7..194c161 100644
--- a/app/helpers/api_taster/application_helper.rb
+++ b/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
diff --git a/app/views/api_taster/routes/show.html.erb b/app/views/api_taster/routes/show.html.erb
index 796ab6e..5716469 100644
--- a/app/views/api_taster/routes/show.html.erb
+++ b/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 %>
 
diff --git a/lib/api_taster/mapper.rb b/lib/api_taster/mapper.rb
index 2cc535c..92dec6f 100644
--- a/lib/api_taster/mapper.rb
+++ b/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
diff --git a/lib/api_taster/route.rb b/lib/api_taster/route.rb
index 06fd747..476d06c 100644
--- a/lib/api_taster/route.rb
+++ b/lib/api_taster/route.rb
@@ -5,6 +5,7 @@ class Route
     cattr_accessor :mappings
     cattr_accessor :supplied_params
     cattr_accessor :obsolete_definitions
+    cattr_accessor :comments
 
     class << self
 
@@ -12,6 +13,7 @@ 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

From 1f1f4ac8c29ea9f24f12de187c4c3c9bf9cc3bb8 Mon Sep 17 00:00:00 2001
From: Emil Melnikov <emilmelnikov@gmail.com>
Date: Tue, 24 Jul 2012 13:18:12 +0400
Subject: [PATCH 2/2] Add tests for endpoint comments

---
 spec/mapper_spec.rb | 13 +++++++++++++
 spec/route_spec.rb  |  6 ++++++
 2 files changed, 19 insertions(+)

diff --git a/spec/mapper_spec.rb b/spec/mapper_spec.rb
index 89be029..9ccbf1e 100644
--- a/spec/mapper_spec.rb
+++ b/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
diff --git a/spec/route_spec.rb b/spec/route_spec.rb
index dfbc95f..89a5d26 100644
--- a/spec/route_spec.rb
+++ b/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