apidoc 0.1.2 → 0.1.3

data/Gemfile

@@ -7,6 +7,7 @@ gem 'thor'
 gem 'mustache'
 gem 'rack-test'
 gem 'mustache'
+gem 'kramdown'
 
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.

data/Gemfile.lock

@@ -9,6 +9,7 @@ GEM
       rake
       rdoc
     json (1.7.3)
+    kramdown (0.13.5)
     mustache (0.99.4)
     rack (1.4.0)
     rack-protection (1.2.0)
@@ -40,6 +41,7 @@ DEPENDENCIES
   bundler (~> 1.0.0)
   jeweler (~> 1.8.3)
   json
+  kramdown
   mustache
   rack-test
   rdoc (~> 3.12)

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.3

data/apidoc.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "apidoc"
-  s.version = "0.1.2"
+  s.version = "0.1.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["T.J. VanSlyke"]
-  s.date = "2012-06-04"
+  s.date = "2012-06-05"
   s.description = "Minimalist API documentation generator for Rack applications."
   s.email = "tj@turing.com"
   s.executables = ["apidoc"]
@@ -36,7 +36,10 @@ Gem::Specification.new do |s|
     "ftags",
     "lib/apidoc.rb",
     "spec/apidoc_spec.rb",
+    "spec/before_and_after_spec.rb",
+    "spec/html_writer_spec.rb",
     "spec/spec_helper.rb",
+    "spec/support/test_apps.rb",
     "templates/apidoc_helper.rb",
     "templates/layout.mustache",
     "templates/resource.mustache"
@@ -55,6 +58,7 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<mustache>, [">= 0"])
       s.add_runtime_dependency(%q<rack-test>, [">= 0"])
       s.add_runtime_dependency(%q<mustache>, [">= 0"])
+      s.add_runtime_dependency(%q<kramdown>, [">= 0"])
       s.add_development_dependency(%q<rspec>, ["~> 2.8.0"])
       s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
       s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
@@ -66,6 +70,7 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<mustache>, [">= 0"])
       s.add_dependency(%q<rack-test>, [">= 0"])
       s.add_dependency(%q<mustache>, [">= 0"])
+      s.add_dependency(%q<kramdown>, [">= 0"])
       s.add_dependency(%q<rspec>, ["~> 2.8.0"])
       s.add_dependency(%q<rdoc>, ["~> 3.12"])
       s.add_dependency(%q<bundler>, ["~> 1.0.0"])
@@ -78,6 +83,7 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<mustache>, [">= 0"])
     s.add_dependency(%q<rack-test>, [">= 0"])
     s.add_dependency(%q<mustache>, [">= 0"])
+    s.add_dependency(%q<kramdown>, [">= 0"])
     s.add_dependency(%q<rspec>, ["~> 2.8.0"])
     s.add_dependency(%q<rdoc>, ["~> 3.12"])
     s.add_dependency(%q<bundler>, ["~> 1.0.0"])

data/examples/burritos_api.html

@@ -108,21 +108,20 @@
 				font-size: 1em;
 			}
 
-			.api-resource .desc {
-				margin: 1em 0;
-				color: 
-				#333;
-				display: block;
-				font-family: Helvetica, sans-serif;
-				font-size: 13px;
-				font-style: normal;
-				font-weight: 100;
-				height: 17px;
-				line-height: 17px;
-				text-shadow: 
-				rgba(255, 255, 255, 0.597656) 0px 1px 0px;
-				vertical-align: baseline;
-			}
+      .api-resource .desc {
+        margin: 1em 0;
+        color: 
+        #333;
+        display: block;
+        font-family: Helvetica, sans-serif;
+        font-size: 13px;
+        font-weight: 100;
+        height: 17px;
+        line-height: 17px;
+        text-shadow: 
+        rgba(255, 255, 255, 0.597656) 0px 1px 0px;
+        vertical-align: baseline;
+      }
 			.api-resource .params,
 			.api-resource .response {
 				font-family: Monaco, fixed;
@@ -159,7 +158,8 @@
       <div class="api-resource">
   <div class="method">GET</div>
   <div class="path">/burritos.json</div>
-  <div class="desc">Get all burritos</div>
+  <div class="desc"><p>Get all burritos. <em>Note:</em> When requesting all burritos, please give the commissary ample time to prepare your order. Fattie.</p>
+</div>
   <div class="params"></div>
   <div class="response">[
   {
@@ -173,7 +173,8 @@
 <div class="api-resource">
   <div class="method">POST</div>
   <div class="path">/burritos.json</div>
-  <div class="desc">Make a new delicious burrito</div>
+  <div class="desc"><p>Make a new delicious burrito</p>
+</div>
   <div class="params">{
   &quot;meat&quot;: &quot;beef&quot;,
   &quot;lettuce&quot;: true
@@ -182,6 +183,18 @@
   &quot;meat&quot;: &quot;beef&quot;,
   &quot;lettuce&quot;: true
 }</div>
+</div>
+<div class="api-resource">
+  <div class="method">GET</div>
+  <div class="path">/burritos/:id.json</div>
+  <div class="desc"><p>Get a burrito by its ID</p>
+</div>
+  <div class="params">{
+}</div>
+  <div class="response">{
+  &quot;meat&quot;: &quot;beef&quot;,
+  &quot;id&quot;: &quot;123&quot;
+}</div>
 </div>
 
     </div>

data/examples/burritos_api.rb

@@ -13,6 +13,10 @@ class BurritoApp < Sinatra::Base
     request.body
   end
 
+  get '/burritos/:id.json' do
+    JSON.generate({ meat: 'beef', id: params['id'] })
+  end
+
 end
 
 doc = ApiDoc.new BurritoApp do
@@ -21,13 +25,20 @@ doc = ApiDoc.new BurritoApp do
   content_type :json
 
   get '/burritos.json' do
-    desc "Get all burritos"
+    desc %{Get all burritos. *Note:* When requesting all burritos, please give the commissary ample time to prepare your order. Fattie.}
   end
 
   post '/burritos.json' do
     desc "Make a new delicious burrito"
     params do
-      JSON.generate({ meat: 'beef', lettuce: true })
+      { meat: 'beef', lettuce: true }
+    end
+  end
+
+  get '/burritos/:id.json' do
+    desc "Get a burrito by its ID"
+    params do
+      { id: 123 }
     end
   end
 

data/examples/tacos_api.html

@@ -108,21 +108,20 @@
 				font-size: 1em;
 			}
 
-			.api-resource .desc {
-				margin: 1em 0;
-				color: 
-				#333;
-				display: block;
-				font-family: Helvetica, sans-serif;
-				font-size: 13px;
-				font-style: normal;
-				font-weight: 100;
-				height: 17px;
-				line-height: 17px;
-				text-shadow: 
-				rgba(255, 255, 255, 0.597656) 0px 1px 0px;
-				vertical-align: baseline;
-			}
+      .api-resource .desc {
+        margin: 1em 0;
+        color: 
+        #333;
+        display: block;
+        font-family: Helvetica, sans-serif;
+        font-size: 13px;
+        font-weight: 100;
+        height: 17px;
+        line-height: 17px;
+        text-shadow: 
+        rgba(255, 255, 255, 0.597656) 0px 1px 0px;
+        vertical-align: baseline;
+      }
 			.api-resource .params,
 			.api-resource .response {
 				font-family: Monaco, fixed;
@@ -158,17 +157,19 @@
       <div class="name"></div>
       <div class="api-resource">
   <div class="method">GET</div>
-  <div class="path">/tacos.json</div>
-  <div class="desc">Get all tacos</div>
+  <div class="path">/tacos</div>
+  <div class="desc"><p>Get all tacos</p>
+</div>
   <div class="params"></div>
   <div class="response">[{&quot;meat&quot;:&quot;chicken&quot;}]</div>
 </div>
 <div class="api-resource">
   <div class="method">POST</div>
-  <div class="path">/tacos.json</div>
-  <div class="desc">Make a new delicious taco</div>
-  <div class="params">{&quot;meat&quot;:&quot;beef&quot;,&quot;lettuce&quot;:true}</div>
-  <div class="response">{&quot;meat&quot;:&quot;beef&quot;,&quot;lettuce&quot;:true}</div>
+  <div class="path">/tacos</div>
+  <div class="desc"><p>Make a new delicious taco</p>
+</div>
+  <div class="params">{:meat=&gt;&quot;beef&quot;, :lettuce=&gt;true}</div>
+  <div class="response">meat=beef&amp;lettuce=true</div>
 </div>
 
     </div>

data/examples/tacos_api.rb

@@ -5,11 +5,11 @@ require 'sinatra/base'
 
 class TacoApp < Sinatra::Base
 
-  get '/tacos.json' do
+  get '/tacos' do
     JSON.generate [ { meat: 'chicken' } ]
   end
 
-  post '/tacos.json' do
+  post '/tacos' do
     request.body
   end
 
@@ -17,14 +17,14 @@ end
 
 doc = ApiDoc.new TacoApp do
 
-  get '/tacos.json' do
+  get '/tacos' do
     desc "Get all tacos"
   end
 
-  post '/tacos.json' do
+  post '/tacos' do
     desc "Make a new delicious taco"
     params do
-      JSON.generate({ meat: 'beef', lettuce: true })
+      { meat: 'beef', lettuce: true }
     end
   end
 

data/ftags

@@ -11,13 +11,21 @@ Gemfile.lock	./Gemfile.lock	/^/;"	r
 LICENSE.txt	./LICENSE.txt	/^/;"	r
 README.rdoc	./README.rdoc	/^/;"	r
 Rakefile	./Rakefile	/^/;"	r
+VERSION	./VERSION	/^/;"	r
 apidoc	./bin/apidoc	/^/;"	r
+apidoc-0.1.2.gem	./pkg/apidoc-0.1.2.gem	/^/;"	r
+apidoc.gemspec	./apidoc.gemspec	/^/;"	r
 apidoc.rb	./lib/apidoc.rb	/^/;"	r
 apidoc_helper.rb	./templates/apidoc_helper.rb	/^/;"	r
 apidoc_spec.rb	./spec/apidoc_spec.rb	/^/;"	r
 authentication.rb	./examples/authentication.rb	/^/;"	r
+before_and_after_spec.rb	./spec/before_and_after_spec.rb	/^/;"	r
+burritos_api.html	./examples/burritos_api.html	/^/;"	r
+burritos_api.rb	./examples/burritos_api.rb	/^/;"	r
 config	./.bundle/config	/^/;"	r
 ftags	./ftags	/^/;"	r
 layout.mustache	./templates/layout.mustache	/^/;"	r
 resource.mustache	./templates/resource.mustache	/^/;"	r
 spec_helper.rb	./spec/spec_helper.rb	/^/;"	r
+tacos_api.html	./examples/tacos_api.html	/^/;"	r
+tacos_api.rb	./examples/tacos_api.rb	/^/;"	r

data/lib/apidoc.rb

@@ -2,6 +2,7 @@ require 'rack/test'
 require 'thor'
 require 'mustache'
 require 'json'
+require 'kramdown'
 
 module ApiDoc
   VERSION = "0.1.0"
@@ -99,6 +100,8 @@ module ApiDoc
     end
 
     def write(stream)
+      @runner.run
+
       stream.write(
         Mustache.to_html(File.read(File.dirname(__FILE__) + '/../templates/layout.mustache'), {
           content: @runner.resources.map {|r| resource_html(r) }.join
@@ -109,39 +112,15 @@ module ApiDoc
     end
 
     def resource_html(resource) 
-      resource.run
-
       Mustache.to_html(File.read(File.dirname(__FILE__) + '/../templates/resource.mustache'), {
         method: resource.method,
         path: resource.path,
-        desc: resource.desc,
-        params: formatted_params(resource),
-        response: formatted_response(resource)
+        desc: Kramdown::Document.new(resource.desc).to_html,
+        params: resource.formatted_params,
+        response: resource.formatted_response
       })
     end
 
-    def formatted_params(resource)
-      return '' unless resource.params
-      return resource.params unless resource.accept
-
-      case resource.accept.intern
-      when :json
-        JSON.pretty_generate(JSON.parse(resource.params))
-      else
-        resource.params
-      end
-    end
-
-    def formatted_response(resource)
-      return resource.response_body unless resource.content_type
-
-      case resource.content_type.intern
-      when :json
-        JSON.pretty_generate(JSON.parse(resource.response_body))
-      else
-        resource.response_body
-      end
-    end
   end
 
   class Resource
@@ -205,22 +184,60 @@ module ApiDoc
     def run
       @before_blocks.each {|block| instance_eval &block }
       @params = @params.call if @params.is_a?(Proc)
-      @response = make_request(@path, @params)
+      @response = make_request
       @after_blocks.each {|block| instance_eval &block }
     end
 
+    def filtered_params
+      params.reject {|k, v| path_captures.include?(k) or path_captures.include?(k.to_s)}
+    end
+
+    def formatted_params
+      return '' unless params
+      return filtered_params unless accept
+
+      case accept.intern
+      when :json
+        JSON.pretty_generate(filtered_params)
+      else
+        filtered_params
+      end
+    end
+
+    def formatted_response
+      return response_body unless content_type
+
+      case content_type.intern
+      when :json
+        JSON.pretty_generate(JSON.parse(response_body))
+      else
+        response_body
+      end
+    end
+
     def response_body
       @response.body
     end
 
-  end
+    PATH_CAPTURE_REGEXP = /:[^\.\/]+/
 
-  class PostResource < Resource
+    def path_captures
+      @path.match(PATH_CAPTURE_REGEXP).to_a.map {|m| m.gsub(':', '').intern }
+    end
 
-    def make_request(path, params)
-      post path, params
+    def interpolated_path
+      @path.gsub(PATH_CAPTURE_REGEXP) do |match|
+        params[match.gsub(':', '').intern]
+      end
+    end
+
+    def make_request
+      self.send(@method.downcase.intern, interpolated_path, formatted_params)
     end
 
+  end
+
+  class PostResource < Resource
     def initialize(runner, path, &block)
       super runner, path, &block
       @method = 'POST'
@@ -228,11 +245,6 @@ module ApiDoc
   end
 
   class GetResource < Resource
-
-    def make_request(path, params)
-      get path, params
-    end
-
     def initialize(runner, path, &block)
       super runner, path, &block
       @method = 'GET'
@@ -240,11 +252,6 @@ module ApiDoc
   end
 
   class PutResource < Resource
-
-    def make_request(path, params)
-      put path, params
-    end
-
     def initialize(runner, path, &block)
       super runner, path, &block
       @method = 'PUT'
@@ -252,11 +259,6 @@ module ApiDoc
   end
 
   class DeleteResource < Resource
-
-    def make_request(path, params)
-      delete path, params
-    end
-
     def initialize(runner, path, &block)
       super runner, path, &block
       @method = 'DELETE'
@@ -264,11 +266,6 @@ module ApiDoc
   end
 
   class OptionsResource < Resource
-
-    def make_request(path, params)
-      options path, params
-    end
-
     def initialize(runner, path, &block)
       super runner, path, &block
       @method = 'OPTIONS'