Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Feature comments #22

Merged
merged 2 commits into from

2 participants

@emilmelnikov

Add descriptions to API endpoints in Markdown format.
Example:
desc "Descrption text"
post "/users", ...

@fredwu fredwu merged commit 9ba8cfe into fredwu:master
@fredwu
Owner

This is fantastic, thanks @emilmelnikov ! Merged. :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Jul 23, 2012
  1. @emilmelnikov

    Add comments to endpoints

    emilmelnikov authored
Commits on Jul 24, 2012
  1. @emilmelnikov
This page is out of date. Refresh to see the latest.
View
1  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'
View
1  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
View
6 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
View
7 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 %>
View
10 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
View
6 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
View
13 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
View
6 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
Something went wrong with that request. Please try again.