Merge branch 'master' into change-json

Author: SqREL

README.md

@@ -102,7 +102,13 @@ RspecApiDocumentation.configure do |config|
   # Allows you to filter out headers that are not needed in the cURL request,
   # such as "Host" and "Cookie". Set as an array.
   config.curl_headers_to_filter = nil
-  
+
+  # By default, when these settings are nil, all headers are shown,
+  # which is sometimes too chatty. Setting the parameters to an
+  # array of headers will render *only* those headers.
+  config.request_headers_to_include = nil
+  config.response_headers_to_include = nil
+
   # By default examples and resources are ordered by description. Set to true keep
   # the source order.
   config.keep_source_order = false

features/combined_json.feature

@@ -24,6 +24,8 @@ Feature: Combined text
       RspecApiDocumentation.configure do |config|
         config.app = App
         config.format = :combined_json
+        config.request_headers_to_include = %w[Host]
+        config.response_headers_to_include = %w[Content-Type]
       end
 
       resource "Greetings" do
@@ -84,8 +86,7 @@ Feature: Combined text
             "request_path": "/greetings?target=rspec_api_documentation",
             "request_body": null,
             "request_headers": {
-              "Host": "example.org",
-              "Cookie": ""
+              "Host": "example.org"
             },
             "request_query_parameters": {
               "target": "rspec_api_documentation"
@@ -95,8 +96,7 @@ Feature: Combined text
             "response_status_text": "OK",
             "response_body": "Hello, rspec_api_documentation!",
             "response_headers": {
-              "Content-Type": "text/plain",
-              "Content-Length": "31"
+              "Content-Type": "text/plain"
             },
             "response_content_type": "text/plain",
             "curl": null
@@ -121,8 +121,7 @@ Feature: Combined text
             "request_path": "/greetings?target=Sam+%26+Eric",
             "request_body": null,
             "request_headers": {
-              "Host": "example.org",
-              "Cookie": ""
+              "Host": "example.org"
             },
             "request_query_parameters": {
               "target": "Sam & Eric"
@@ -132,8 +131,7 @@ Feature: Combined text
             "response_status_text": "OK",
             "response_body": "Hello, Sam & Eric!",
             "response_headers": {
-              "Content-Type": "text/plain",
-              "Content-Length": "18"
+              "Content-Type": "text/plain"
             },
             "response_content_type": "text/plain",
             "curl": null

features/html_documentation.feature

@@ -21,11 +21,14 @@ Feature: Generate HTML documentation from test examples
       RspecApiDocumentation.configure do |config|
         config.app = App
         config.api_name = "Example API"
+        config.request_headers_to_include = %w[Cookie]
+        config.response_headers_to_include = %w[Content-Type]
       end
 
       resource "Greetings" do
         get "/greetings" do
           parameter :target, "The thing you want to greet"
+          parameter :scoped, "This is a scoped variable", :scope => :scope
 
           example "Greeting your favorite gem" do
             do_request :target => "rspec_api_documentation"
@@ -60,16 +63,18 @@ Feature: Generate HTML documentation from test examples
     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 |
+      | name          | description                 |
+      | target        | The thing you want to greet |
+      | scope[scoped] | This is a scoped variable   |
 
   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 not see the following request headers:
+      | Host   | example.org |
     And   I should see the following query parameters:
       | target | rspec_api_documentation |
 
@@ -79,6 +84,7 @@ Feature: Generate HTML documentation from test examples
     Then  I should see the response status is "200 OK"
     And   I should see the following response headers:
       | Content-Type   | application/json |
+    And   I should not see the following response headers:
       | Content-Length | 35               |
     And   I should see the following response body:
       """

features/step_definitions/html_steps.rb

@@ -26,6 +26,15 @@
   end
 end
 
+Then /^I should not see the following (request|response) headers:$/ do |part, table|
+  actual_headers = page.find("pre.#{part}.headers").text
+  expected_headers = table.raw.map { |row| row.join(": ") }
+
+  expected_headers.each do |row|
+    actual_headers.should_not include(row.strip)
+  end
+end
+
 Then /^I should see the route is "([^"]*)"$/ do |route|
   page.should have_css(".request.route", :text => route)
 end

features/textile_documentation.feature

@@ -45,6 +45,8 @@ Feature: Generate Textile documentation from test examples
         config.app = App
         config.api_name = "Example API"
         config.format = :textile
+        config.request_headers_to_include = %w[Content-Type Host]
+        config.response_headers_to_include = %w[Content-Type Content-Length]
       end
 
       resource 'Orders' do
@@ -180,8 +182,7 @@ Feature: Generate Textile documentation from test examples
     h4. Headers
 
     <pre>Host: example.org
-    Content-Type: application/x-www-form-urlencoded
-    Cookie: </pre>
+    Content-Type: application/x-www-form-urlencoded</pre>
 
     h4. Route
 
@@ -198,10 +199,7 @@ Feature: Generate Textile documentation from test examples
     h4. Headers
 
     <pre>Content-Type: text/html;charset=utf-8
-    Content-Length: 0
-    X-XSS-Protection: 1; mode=block
-    X-Content-Type-Options: nosniff
-    X-Frame-Options: SAMEORIGIN</pre>
+    Content-Length: 0</pre>
 
     h4. Status
 

lib/rspec_api_documentation/configuration.rb

@@ -61,6 +61,8 @@ def self.add_setting(name, opts = {})
     add_setting :keep_source_order, :default => false
     add_setting :api_name, :default => "API Documentation"
     add_setting :io_docs_protocol, :default => "http"
+    add_setting :request_headers_to_include, :default => nil
+    add_setting :response_headers_to_include, :default => nil
 
     def client_method=(new_client_method)
       RspecApiDocumentation::DSL::Resource.module_eval <<-RUBY

lib/rspec_api_documentation/curl.rb

@@ -69,7 +69,7 @@ def format_header(header)
     end
 
     def format_full_header(header, value)
-      formatted_value = value.gsub(/"/, "\\\"")
+      formatted_value = value ? value.gsub(/"/, "\\\"") : ''
       "#{format_header(header)}: #{formatted_value}"
     end
 

lib/rspec_api_documentation/example.rb

@@ -43,7 +43,25 @@ def explanation
     end
 
     def requests
-      metadata[:requests] || []
+      filter_headers(metadata[:requests]) || []
+    end
+
+    private
+
+    def filter_headers(requests)
+      requests = remap_headers(requests, :request_headers, configuration.request_headers_to_include)
+      requests = remap_headers(requests, :response_headers, configuration.response_headers_to_include)
+      requests
+    end
+
+    def remap_headers(requests, key, headers_to_include)
+      return requests unless headers_to_include
+      requests.each.with_index do |request_hash, index|
+        next unless request_hash.key?(key)
+        headers = request_hash[key]
+        request_hash[key] = headers.select{ |key, _| headers_to_include.include?(key) }
+        requests[index] = request_hash
+      end
     end
   end
 end

spec/configuration_spec.rb

@@ -54,6 +54,8 @@
     its(:api_name) { should == "API Documentation" }
     its(:client_method) { should == :client }
     its(:io_docs_protocol) { should == "http" }
+    its(:request_headers_to_include) { should be_nil }
+    its(:response_headers_to_include) { should be_nil }
   end
 
   describe "#define_groups" do

spec/curl_spec.rb

@@ -15,7 +15,8 @@
         "HTTP_X_HEADER" => "header",
         "HTTP_AUTHORIZATION" => %{Token token="mytoken"},
         "HTTP_HOST" => "example.org",
-        "HTTP_COOKIES" => ""
+        "HTTP_COOKIES" => "",
+        "HTTP_SERVER" => nil
       }
     end
 
@@ -26,6 +27,7 @@
     it { should =~ /-H "Accept: application\/json"/ }
     it { should =~ /-H "X-Header: header"/ }
     it { should =~ /-H "Authorization: Token token=\\"mytoken\\""/ }
+    it { should =~ /-H "Server: "/ }
     it { should_not =~ /-H "Host: example\.org"/ }
     it { should_not =~ /-H "Cookies: "/ }
 

spec/example_spec.rb

@@ -159,4 +159,82 @@
       example.explanation.should == nil
     end
   end
+
+  describe "request headers can be filtered" do
+    before do
+      configuration.request_headers_to_include = %w[Included]
+      metadata[:requests] = [
+          {
+              :request_headers => {
+                  "Included" => "data",
+                  "Filtered" => "not seen"
+              },
+              :request_method => "GET"
+          },
+          {
+              :request_headers => {
+                  "Included" => "data",
+                  "Other" => "not seen"
+              },
+              :request_method => "GET"
+          }
+      ]
+    end
+
+    it "should filter out anything not explicitly mentioned" do
+      subject.requests.should == [
+          {
+              :request_headers => {
+                  "Included" => "data",
+              },
+              :request_method => "GET"
+          },
+          {
+              :request_headers => {
+                  "Included" => "data",
+              },
+              :request_method => "GET"
+          }
+      ]
+    end
+  end
+
+  describe "response headers can be filtered" do
+    before do
+      configuration.response_headers_to_include = %w[Included]
+      metadata[:requests] = [
+          {
+              :response_headers => {
+                  "Included" => "data",
+                  "Filtered" => "not seen"
+              },
+              :request_method => "GET"
+          },
+          {
+              :response_headers => {
+                  "Included" => "data",
+                  "Other" => "not seen"
+              },
+              :request_method => "GET"
+          }
+      ]
+    end
+
+    it "should filter out anything not explicitly mentioned" do
+      subject.requests.should == [
+          {
+              :response_headers => {
+                  "Included" => "data",
+              },
+              :request_method => "GET"
+          },
+          {
+              :response_headers => {
+                  "Included" => "data",
+              },
+              :request_method => "GET"
+          }
+      ]
+    end
+  end
 end

templates/rspec_api_documentation/html_example.mustache

@@ -53,7 +53,12 @@
               {{# parameters }}
               <tr>
                 <td{{# required }} class="required"{{/ required }}>
-                  <span class="name">{{ name }}</span>
+                  {{# scope }}
+                    <span class="name">{{ scope }}[{{ name }}]</span>
+                  {{/ scope }}
+                  {{^ scope }}
+                    <span class="name">{{ name }}</span>
+                  {{/ scope }}
                 </td>
                 <td>
                   <span class="description">{{ description }}</span>