Merge pull request #118 from Pact/header-filters

Filter request and/or response headers by configuration

Author: oestrich

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,6 +21,8 @@ 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
@@ -70,8 +72,9 @@ Feature: Generate HTML documentation from test examples
     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 |
 
@@ -81,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

@@ -59,6 +59,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/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/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