api_taster 0.4.8 → 0.5.0

data/README.md

@@ -34,6 +34,7 @@ In `routes.rb`, define parameters for each API endpoint after the normal routes
 ```ruby
 if Rails.env.development?
   ApiTaster.routes do
+    desc 'Get a __list__ of users'
     get '/users'
 
     post '/users', {
@@ -78,6 +79,27 @@ ApiTaster.routes do
 end
 ```
 
+### Commenting API Endpoints
+
+Before each route definitions, you may use `desc` to add some comments. Markdown is supported.
+
+```ruby
+desc 'Get a __list__ of users'
+get '/users'
+```
+
+### Metadata for API Endpoints
+
+For each route definition, you may supply an optional third parameter (hash) as metadata:
+
+```ruby
+get '/users', {}, { :meta => 'data' }
+```
+
+The metadata option is useful for passing in arbitrary data for a route definition. For example, you could specify response expectations so that your test suite could tap into them.
+
+Metadata for every route definition are stored in `ApiTaster::Route.metadata`. Please read the source code to find out how to get metadata for a particular route.
+
 ### Missing Route Definitions Detection
 
 Instead of manually finding out which route definitions you need, API Taster provides a warning page that shows you all the missing definitions.

data/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'

data/app/controllers/api_taster/routes_controller.rb

@@ -9,8 +9,9 @@ module ApiTaster
     end
 
     def show
-      @route  = Route.find(params[:id])
-      @params = Route.params_for(@route)
+      @route   = Route.find(params[:id])
+      @params  = Route.params_for(@route)
+      @comment = Route.comment_for(@route)
     end
 
     def missing_definitions

data/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

data/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 %>
 

data/lib/api_taster/form_builder.rb

@@ -8,12 +8,12 @@ module ApiTaster
 
     def initialize(params)
       flush_output_buffer
-      @_buffer = '<legend class="hero-legend"></legend>'
+      @_buffer = ''
       add_to_buffer(params)
     end
 
     def html
-      @_buffer
+      "<legend class=\"hero-legend\"></legend>#{@_buffer}"
     end
 
     private

data/lib/api_taster/mapper.rb

@@ -1,25 +1,31 @@
 module ApiTaster
   class Mapper
+    cattr_accessor :last_desc
+
     class << self
-      def get(path, params = {})
-        map_method(:get, path, params)
+      def get(path, params = {}, metadata = {})
+        map_method(:get, path, params, metadata)
+      end
+
+      def post(path, params = {}, metadata = {})
+        map_method(:post, path, params, metadata)
       end
 
-      def post(path, params = {})
-        map_method(:post, path, params)
+      def put(path, params = {}, metadata = {})
+        map_method(:put, path, params, metadata)
       end
 
-      def put(path, params = {})
-        map_method(:put, path, params)
+      def delete(path, params = {}, metadata = {})
+        map_method(:delete, path, params, metadata)
       end
 
-      def delete(path, params = {})
-        map_method(:delete, path, params)
+      def desc(text)
+        self.last_desc = text
       end
 
       private
 
-      def map_method(method, path, params)
+      def map_method(method, path, params, metadata)
         route = Route.find_by_verb_and_path(method, path)
 
         if route.nil?
@@ -31,6 +37,15 @@ module ApiTaster
         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
+
+          if metadata.any?
+            Route.metadata[route[:id]] = metadata
+          end
         end
       end
     end

data/lib/api_taster/route.rb

@@ -5,6 +5,8 @@ module ApiTaster
     cattr_accessor :mappings
     cattr_accessor :supplied_params
     cattr_accessor :obsolete_definitions
+    cattr_accessor :comments
+    cattr_accessor :metadata
 
     class << self
 
@@ -12,6 +14,8 @@ module ApiTaster
         self.route_set            = Rails.application.routes
         self.supplied_params      = {}
         self.obsolete_definitions = []
+        self.comments             = {}
+        self.metadata             = {}
 
         normalise_routes!
 
@@ -31,6 +35,7 @@ module ApiTaster
         end
 
         route_set.routes.each do |route|
+          next if route.app.is_a?(ActionDispatch::Routing::Mapper::Constraints)
           next if route.app.is_a?(Sprockets::Environment)
           next if route.app == ApiTaster::Engine
 
@@ -71,6 +76,18 @@ module ApiTaster
         supplied_params[route[:id]].collect { |input| split_input(input, route) }
       end
 
+      def comment_for(route)
+        unless undefined_route?(route)
+          self.comments[route[:id].to_i]
+        end
+      end
+
+      def metadata_for(route)
+        unless undefined_route?(route)
+          self.metadata[route[:id].to_i]
+        end
+      end
+
       def defined_definitions
         routes.reject { |route| undefined_route?(route) }
       end

data/lib/api_taster/version.rb

@@ -1,3 +1,3 @@
 module ApiTaster
-  VERSION = "0.4.8"
+  VERSION = "0.5.0"
 end

data/spec/controllers/api_taster/routes_controller_spec.rb

@@ -21,11 +21,13 @@ module ApiTaster
     it "#show" do
       Route.stub(:find).and_return(Route.new)
       Route.stub(:params_for).and_return([])
+      Route.stub(:comment_for).and_return([])
 
       get :show, :id => 1, :use_route => :api_taster
 
       assigns(:route).should be_kind_of(Route)
       assigns(:params).should be_kind_of(Array)
+      assigns(:comment).should be_kind_of(Array)
     end
 
     it "#missing_definitions" do

data/spec/dummy/config/routes.rb

@@ -10,14 +10,11 @@ Rails.application.routes.draw do
 end
 
 ApiTaster.routes do
-  ApiTaster.global_params = {
-    :version => 1
-  }
-
   get '/i_dont_exist_anymore', {
     :hello => 'world'
   }
 
+  desc 'Get a __list__ of users.'
   get '/users'
 
   post '/users', {

data/spec/form_builder_spec.rb

@@ -48,12 +48,12 @@ module ApiTaster
       end
 
       it "does arrays" do
-        builder.html.should match(/name="\[user\]\[comment\]\[title\]\[\]" value="1"/)
+        builder.html.should match(/name="user\[comment\]\[title\]\[\]" value="1"/)
       end
 
       it "does nested arrays" do
-        builder.html.should match(/name="\[items\]\[\]\[nested_items\]\[\]\[nested_numbers\]\[\]" value="5"/)
-        builder.html.should match(/name="\[items\]\[\]\[nested_items\]\[\]\[name\]" value="apple"/)
+        builder.html.should match(/name="items\[\]\[nested_items\]\[\]\[nested_numbers\]\[\]" value="5"/)
+        builder.html.should match(/name="items\[\]\[nested_items\]\[\]\[name\]" value="apple"/)
       end
     end
   end

data/spec/helpers/api_taster/application_helper_spec.rb

@@ -0,0 +1,9 @@
+require 'spec_helper'
+
+module ApiTaster
+  describe ApplicationHelper do
+    it "#markdown" do
+      helper.markdown('__bold__').should == "<p><strong>bold</strong></p>\n"
+    end
+  end
+end

data/spec/mapper_spec.rb

@@ -46,9 +46,10 @@ 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' }
+        post '/dummy_users', { :hello => 'world' }, { :meta => 'data' }
         put '/dummy_users/:id', :id => 2
         delete '/dummy_users/:id', :id => 3
       end
@@ -79,5 +80,29 @@ 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).should == "Dummy user ID"
+    end
+
+    it "doesn't describe a route" do
+      route = Route.find_by_verb_and_path(:post, '/dummy_users')
+
+      Route.comment_for(route).should be_nil
+    end
+
+    it "meta data for a route" do
+      route = Route.find_by_verb_and_path(:post, '/dummy_users')
+
+      Route.metadata_for(route).should == { :meta => 'data' }
+    end
+
+    it "empty meta data for a route" do
+      route = Route.find_by_verb_and_path(:get, '/dummy_users')
+
+      Route.metadata_for(route).should == nil
+    end
   end
 end

data/spec/route_spec.rb

@@ -75,24 +75,42 @@ module ApiTaster
       Route.find_by_verb_and_path(:delete, '/home').should == nil
     end
 
-    it "#params_for" do
-      Route.stub(:routes).and_return([{
-        :id   => 0,
-        :path => '/dummy/:dummy_id'
-      }, {
-        :id   => 999,
-        :path => 'a_non_existing_dummy',
-        :verb => 'get'
-      }])
-      Route.supplied_params[0] = [{ :dummy_id => 1, :hello => 'world' }]
-
-      Route.params_for(Route.find(999)).should have_key(:undefined)
-
-      2.times do
-        Route.params_for(Route.find(0)).should == [{
-          :url_params  => { :dummy_id => 1 },
-          :post_params => { :hello => 'world' }
-        }]
+    context "get data of a route" do
+      before do
+        Route.stub(:routes).and_return([{
+          :id   => 0,
+          :path => '/dummy/:dummy_id'
+        }, {
+          :id   => 999,
+          :path => 'a_non_existing_dummy',
+          :verb => 'get'
+        }])
+        Route.supplied_params[0] = [{ :dummy_id => 1, :hello => 'world' }]
+      end
+
+      it "#params_for" do
+        Route.params_for(Route.find(999)).should have_key(:undefined)
+
+        2.times do
+          Route.params_for(Route.find(0)).should == [{
+            :url_params  => { :dummy_id => 1 },
+            :post_params => { :hello => 'world' }
+          }]
+        end
+      end
+
+      it "#comment_for" do
+        markdown_comment = "Heading\n=======\n * List item 1\n * List item 2"
+        Route.comments[0] = markdown_comment
+
+        Route.comment_for(Route.find(0)).should == markdown_comment
+      end
+
+      it "#metadata_for" do
+        metadata = { :hello => 'world' }
+        Route.metadata[0] = metadata
+
+        Route.metadata_for(Route.find(0)).should == metadata
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_taster
 version: !ruby/object:Gem::Version
-  version: 0.4.8
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-16 00:00:00.000000000 Z
+date: 2012-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -75,6 +75,22 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 2.0.3
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -230,6 +246,7 @@ files:
 - spec/dummy/log/.gitkeep
 - spec/dummy/script/rails
 - spec/form_builder_spec.rb
+- spec/helpers/api_taster/application_helper_spec.rb
 - spec/mapper_spec.rb
 - spec/route_spec.rb
 - spec/spec_helper.rb
@@ -466,7 +483,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 868374881218016492
+      hash: -1701071876129671469
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -475,7 +492,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 868374881218016492
+      hash: -1701071876129671469
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
@@ -727,6 +744,7 @@ test_files:
 - spec/dummy/tmp/cache/sass/fced329c33ec1fff188d99efbc4d1fd1c556b66a/layout.css.scssc
 - spec/dummy/tmp/pids/server.pid
 - spec/form_builder_spec.rb
+- spec/helpers/api_taster/application_helper_spec.rb
 - spec/mapper_spec.rb
 - spec/route_spec.rb
 - spec/spec_helper.rb