Add comments to endpoints

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