Merge branch 'master' of github.com:zipmark/rspec_api_documentation

Author: oestrich

.gitignore

@@ -0,0 +1 @@
+tmp

Gemfile.lock

@@ -16,14 +16,39 @@ GEM
     activesupport (3.1.3)
       multi_json (~> 1.0)
     addressable (2.2.6)
+    aruba (0.4.11)
+      childprocess (>= 0.2.3)
+      cucumber (>= 1.1.1)
+      ffi (>= 1.0.11)
+      rspec (>= 2.7.0)
     builder (3.0.0)
+    capybara (1.1.2)
+      mime-types (>= 1.16)
+      nokogiri (>= 1.3.3)
+      rack (>= 1.0.0)
+      rack-test (>= 0.5.4)
+      selenium-webdriver (~> 2.0)
+      xpath (~> 0.1.4)
+    childprocess (0.3.1)
+      ffi (~> 1.0.6)
     crack (0.3.1)
+    cucumber (1.1.8)
+      builder (>= 2.1.2)
+      diff-lcs (>= 1.1.2)
+      gherkin (~> 2.8.0)
+      json (>= 1.4.6)
+      term-ansicolor (>= 1.0.6)
     diff-lcs (1.1.3)
     fakefs (0.4.0)
+    ffi (1.0.11)
+    gherkin (2.8.0)
+      json (>= 1.4.6)
     i18n (0.6.0)
-    json (1.6.3)
+    json (1.6.5)
+    mime-types (1.17.2)
     multi_json (1.0.4)
     mustache (0.99.4)
+    nokogiri (1.5.0)
     rack (1.3.5)
     rack-test (0.6.1)
       rack (>= 1.0)
@@ -35,19 +60,30 @@ GEM
     rspec-expectations (2.8.0)
       diff-lcs (~> 1.1.2)
     rspec-mocks (2.8.0)
+    rubyzip (0.9.6.1)
+    selenium-webdriver (2.19.0)
+      childprocess (>= 0.2.5)
+      ffi (~> 1.0.9)
+      multi_json (~> 1.0.4)
+      rubyzip
     sinatra (1.2.6)
       rack (~> 1.1)
       tilt (>= 1.2.2, < 2.0)
+    term-ansicolor (1.0.7)
     tilt (1.3.3)
     webmock (1.7.10)
       addressable (~> 2.2, > 2.2.5)
       crack (>= 0.1.7)
+    xpath (0.1.4)
+      nokogiri (~> 1.3)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  aruba
   builder
+  capybara
   fakefs
   rspec_api_documentation!
   sinatra

features/html_documentation.feature

@@ -0,0 +1,98 @@
+Feature: Generate HTML documentation from test examples
+
+  Background:
+    Given a file named "app.rb" with:
+      """
+      require "sinatra/base"
+
+      class App < Sinatra::Base
+        before do
+          content_type :json
+        end
+
+        get "/greetings" do
+          if target = params["target"]
+            { "hello" => params["target"] }.to_json
+          else
+            422
+          end
+        end
+      end
+      """
+    And   a file named "app_spec.rb" with:
+      """
+      require "active_support/inflector"
+      require "rspec_api_documentation"
+      require "rspec_api_documentation/dsl"
+
+      RspecApiDocumentation.configure do |config|
+        config.app = App
+      end
+
+      resource "Greetings" do
+        get "/greetings" do
+          parameter :target, "The thing you want to greet"
+
+          example "Greeting your favorite gem" do
+            do_request :target => "rspec_api_documentation"
+
+            status.should eq(200)
+            response_body.should eq('{"hello":"rspec_api_documentation"}')
+          end
+        end
+      end
+      """
+    When  I run `rspec app_spec.rb --require ./app.rb --format RspecApiDocumentation::ApiFormatter`
+
+  Scenario: Output helpful progress to the console
+    Then  the output should contain:
+      """
+      Generating API Docs
+        Greetings
+        GET /greetings
+          * Greeting your favorite gem
+      """
+    And   the output should contain "1 example, 0 failures"
+    And   the exit status should be 0
+
+  Scenario: Create an index of all API examples, including all resources
+    When  I open the index
+    Then  I should see the following resources:
+      | Greetings |
+
+  Scenario: Example HTML documentation includes the parameters
+    When  I open the index
+    And   I navigate to "Greeting your favorite gem"
+    Then  I should see the following parameters:
+      | name   | description                 |
+      | target | The thing you want to greet |
+
+  Scenario: Example HTML documentation includes the request information
+    When  I open the index
+    And   I navigate to "Greeting your favorite gem"
+    Then  I should see the route is "GET /greetings?target=rspec_api_documentation"
+    And   I should see the following request headers:
+      """
+      Host: example.org
+      Cookie: 
+      """
+    And   I should see the following query parameters:
+      """
+      target: rspec_api_documentation
+      """
+
+  Scenario: Example HTML documentation includes the response information
+    When  I open the index
+    And   I navigate to "Greeting your favorite gem"
+    Then  I should see the response status is "200 OK"
+    And   I should see the following response headers:
+      """
+      Content-Type: application/json
+      Content-Length: 35
+      """
+    And   I should see the following response_body:
+      """
+      {
+        "hello" => "rspec_api_documentation"
+      }
+      """

features/step_definitions/html_steps.rb

@@ -0,0 +1,37 @@
+When /^I open the index$/ do
+  visit "/index.html"
+end
+
+When /^I navigate to "([^"]*)"$/ do |example|
+  click_link example
+end
+
+Then /^I should see the following resources:$/ do |table|
+  all("h2").map(&:text).should == table.raw.flatten
+end
+
+Then /^I should see the following parameters:$/ do |table|
+  names = all(".parameters .name").map(&:text)
+  descriptions = all(".parameters .description").map(&:text)
+  names.zip(descriptions).should == table.rows
+end
+
+Then /^I should see the following (request|response) headers:$/ do |part, headers|
+  page.should have_css("pre.#{part}.headers", :content => headers)
+end
+
+Then /^I should see the route is "([^"]*)"$/ do |route|
+  page.should have_css(".request.route", :content => route)
+end
+
+Then /^I should see the following query parameters:$/ do |query_parameters|
+  page.should have_css("pre.request.query_parameters"), :content => query_parameters
+end
+
+Then /^I should see the response status is "([^"]*)"$/ do |status|
+  page.should have_css(".response.status", :content => status)
+end
+
+Then /^I should see the following response_body:$/ do |response_body|
+  page.should have_css("pre.response.body", :content => response_body)
+end

features/support/capybara.rb

@@ -0,0 +1,19 @@
+require 'rack'
+require 'capybara/cucumber'
+
+# Wire up Capybara to test again static files served by Rack
+# Courtesy of http://opensoul.org/blog/archives/2010/05/11/capybaras-eating-cucumbers/
+
+root_dir = File.join(File.dirname(__FILE__), '..', '..', 'tmp', 'aruba', 'docs')
+
+Capybara.app = Rack::Builder.new do
+  map "/" do
+    # use Rack::CommonLogger, $stderr
+    use Rack::Static, :urls => ["/"], :root => root_dir
+    use Rack::Lint
+    run lambda {|env| [404, {}, '']}
+  end
+end.to_app
+
+Capybara.default_selector = :css
+Capybara.default_driver   = :rack_test

features/support/env.rb

@@ -0,0 +1,6 @@
+# Aruba has an important step that is only on git right now, so we need to
+# explicitly load the development bundle because gemspecs can't point to git
+require "bundler"
+Bundler.setup(:development)
+
+require "aruba/cucumber"

rspec_api_documentation.gemspec

@@ -25,6 +25,8 @@ Gem::Specification.new do |s|
   s.add_development_dependency "fakefs"
   s.add_development_dependency "sinatra"
   s.add_development_dependency "builder"
+  s.add_development_dependency "aruba"
+  s.add_development_dependency "capybara"
 
   s.files        = Dir.glob("lib/**/*")
   s.require_path = 'lib'

templates/rspec_api_documentation/html_example.mustache

@@ -30,7 +30,7 @@
 
         {{# has_parameters? }}
           <h3>Parameters</h3>
-          <table>
+          <table class="parameters">
             <thead>
               <tr>
                 <th>Name</th>
@@ -40,7 +40,7 @@
             <tbody>
               {{# parameters }}
               <tr>
-                <td{{# required }} class="required"{{/ required }}>
+                <th{{# required }} class="required"{{/ required }}>
                   <span class="name">{{ name }}</span>
                 </td>
                 <td>
@@ -55,12 +55,12 @@
         {{# requests }}
           <h3>Request</h3>
           <h4>Headers</h4>
-          <pre class="headers">{{ request_headers }}</pre>
+          <pre class="request headers">{{ request_headers }}</pre>
           <h4>Route</h4>
-          <pre class="request highlight">{{ method }} {{ route }}</pre>
+          <pre class="request route highlight">{{ method }} {{ route }}</pre>
           {{# request_query_parameters }}
             <h4>Query Parameters</h4>
-            <pre class="request highlight">{{ request_query_parameters }}</pre>
+            <pre class="request query_parameters highlight">{{ request_query_parameters }}</pre>
           {{/ request_query_parameters }}
           {{# request_body }}
             <h4>Body</h4>
@@ -75,12 +75,12 @@
           {{# response_status }}
             <h3>Response</h3>
             <h4>Headers</h4>
-            <pre class="headers">{{ response_headers }}</pre>
+            <pre class="response headers">{{ response_headers }}</pre>
             <h4>Status</h4>
-            <pre class="response_status">{{ response_status }} {{ response_status_text}}</pre>
+            <pre class="response status">{{ response_status }} {{ response_status_text}}</pre>
             {{# response_body }}
               <h4>Body</h4>
-              <pre class="response highlight">{{ response_body }}</pre>
+              <pre class="response body highlight">{{ response_body }}</pre>
             {{/ response_body }}
           {{/ response_status }}
         {{/ requests }}