rspec_api_documentation 0.6.0 → 0.7.1

data/lib/rspec_api_documentation/client_base.rb

@@ -21,14 +21,18 @@ module RspecApiDocumentation
       process :delete, *args
     end
 
+    def response_status
+      status
+    end
+
     private
 
-    def process(method, path, params = {})
-      do_request(method, path, params)
-      document_example(method.to_s.upcase, path, params)
+    def process(method, path, params = {}, headers ={})
+      do_request(method, path, params, headers)
+      document_example(method.to_s.upcase, path)
     end
 
-    def document_example(method, path, params)
+    def document_example(method, path)
       return unless metadata[:document]
 
       input = last_request.env["rack.input"]
@@ -63,12 +67,8 @@ module RspecApiDocumentation
       Hash[arrays]
     end
 
-    def headers(method, path, params)
-      if options && options[:headers]
-        options[:headers]
-      else
-        {}
-      end
+    def headers(method, path, params, request_headers)
+      request_headers || {}
     end
   end
 end

data/lib/rspec_api_documentation/combined_json_writer.rb

@@ -0,0 +1,18 @@
+require 'rspec_api_documentation/json_writer'
+
+module RspecApiDocumentation
+  class CombinedJsonWriter
+    def self.write(index, configuration)
+      File.open(configuration.docs_dir.join("combined.json"), "w+") do |f|
+        examples = []
+        index.examples.each do |rspec_example|
+          examples << JsonExample.new(rspec_example, configuration).to_json
+        end
+
+        f.write "["
+        f.write examples.join(",")
+        f.write "]"
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/combined_text_writer.rb

@@ -0,0 +1,100 @@
+module RspecApiDocumentation
+  class CombinedTextWriter
+    def self.write(index, configuration)
+      index.examples.each do |rspec_example|
+        example = CombinedTextExample.new(rspec_example)
+        FileUtils.mkdir_p(configuration.docs_dir.join(example.resource_name))
+        File.open(configuration.docs_dir.join(example.resource_name, "index.txt"), "a+") do |f|
+          f.print example.description
+          f.print example.parameters
+
+          example.requests.each do |request, response|
+            f.puts "Request:"
+            f.puts request
+            f.puts
+            f.puts "Response:"
+            f.puts response
+          end
+
+          unless rspec_example == index.examples.last
+            f.puts
+            f.puts
+          end
+        end
+      end
+    end
+
+    def self.format_hash(hash, separator="=")
+      hash.sort_by { |k, v| k }.inject("") do |out, (k, v)|
+        out << "  #{k}#{separator}#{v}\n"
+      end
+    end
+  end
+
+  class CombinedTextExample
+    attr_reader :example
+
+    def initialize(example)
+      @example = example
+    end
+
+    def resource_name
+      example.resource_name.downcase.gsub(/\s+/, '_')
+    end
+
+    def description
+      example.description + "\n" + "-" * example.description.length + "\n\n"
+    end
+
+    def parameters
+      return "" unless example.metadata[:parameters]
+      "Parameters:\n" + example.metadata[:parameters].inject("") do |out, parameter|
+        out << "  * #{parameter[:name]} - #{parameter[:description]}\n"
+      end + "\n"
+    end
+
+    def requests
+      return [] unless example.metadata[:requests]
+      example.metadata[:requests].map do |request|
+        [format_request(request), format_response(request)]
+      end
+    end
+
+    private
+    def format_request(request)
+      [
+        [
+          "  #{request[:request_method]} #{request[:request_path]}",
+          format_hash(request[:request_headers], ": ")
+        ],
+        [
+          format_string(request[:request_body]) || format_hash(request[:request_query_parameters])
+        ]
+      ].map { |x| x.compact.join("\n") }.reject(&:blank?).join("\n\n") + "\n"
+    end
+
+    def format_response(request)
+      [
+        [
+          "  Status: #{request[:response_status]} #{request[:response_status_text]}",
+          format_hash(request[:response_headers], ": ")
+        ],
+        [
+          format_string(request[:response_body])
+        ]
+      ].map { |x| x.compact.join("\n") }.reject(&:blank?).join("\n\n") + "\n"
+    end
+
+    def format_string(string)
+      return unless string
+      string.split("\n").map { |line| "  #{line}" }.join("\n")
+    end
+
+    def format_hash(hash, separator="=")
+      return unless hash
+      hash.sort_by { |k, v| k }.map do |k, v|
+        "  #{k}#{separator}#{v}"
+      end.join("\n")
+    end
+  end
+end

data/lib/rspec_api_documentation/configuration.rb

@@ -17,6 +17,7 @@ module RspecApiDocumentation
       subconfig = self.class.new(self)
       subconfig.filter = name
       subconfig.docs_dir = self.docs_dir.join(name.to_s)
+      subconfig.url_prefix = "#{self.url_prefix}/#{name}"
       yield subconfig
       groups << subconfig
     end
@@ -57,6 +58,7 @@ module RspecApiDocumentation
 
     add_setting :curl_host, :default => nil
     add_setting :keep_source_order, :default => false
+    add_setting :api_name, :default => "API Documentation"
 
     def settings
       @settings ||= {}

data/lib/rspec_api_documentation/dsl/endpoint.rb

@@ -4,7 +4,7 @@ module RspecApiDocumentation::DSL
   module Endpoint
     extend ActiveSupport::Concern
 
-    delegate :response_headers, :status, :response_body, :to => :client
+    delegate :response_headers, :status, :response_status, :response_body, :to => :client
 
     module ClassMethods
       def example_request(description, params = {}, &block)
@@ -41,7 +41,7 @@ module RspecApiDocumentation::DSL
         params_or_body = respond_to?(:raw_post) ? raw_post : params
       end
 
-      client.send(method, path_or_query, params_or_body)
+      client.send(method, path_or_query, params_or_body, headers)
     end
 
     def query_string
@@ -61,6 +61,10 @@ module RspecApiDocumentation::DSL
       parameters
     end
 
+    def headers
+      example.metadata[:headers]
+    end
+
     def method
       example.metadata[:method]
     end

data/lib/rspec_api_documentation/dsl/resource.rb

@@ -35,6 +35,10 @@ module RspecApiDocumentation::DSL
         parameters.push(options.merge(:name => name.to_s, :description => description))
       end
 
+      def header(name, value)
+        headers[name] = value
+      end
+
       def required_parameters(*names)
         names.each do |name|
           param = parameters.find { |param| param[:name] == name.to_s }
@@ -67,6 +71,14 @@ module RspecApiDocumentation::DSL
         metadata[:parameters]
       end
 
+      def headers
+        metadata[:headers] ||= {}
+        if superclass_metadata && metadata[:headers].equal?(superclass_metadata[:headers])
+          metadata[:headers] = Marshal.load(Marshal.dump(superclass_metadata[:headers]))
+        end
+        metadata[:headers]
+      end
+
       def parameter_keys
         parameters.map { |param| param[:name] }
       end

data/lib/rspec_api_documentation/headers.rb

@@ -14,6 +14,15 @@ module RspecApiDocumentation
       headers
     end
 
+    def headers_to_env(headers)
+      headers.inject({}) do |hsh, (k, v)|
+        new_key = k.upcase.gsub("-", "_")
+        new_key = "HTTP_#{new_key}" unless new_key == "CONTENT_TYPE"
+        hsh[new_key] = v
+        hsh
+      end
+    end
+
     def format_headers(headers)
       headers.map do |key, value|
         "#{key}: #{value}"

data/lib/rspec_api_documentation/html_writer.rb

@@ -35,6 +35,10 @@ module RspecApiDocumentation
       self.template_path = configuration.template_path
     end
 
+    def api_name
+      @configuration.api_name
+    end
+
     def sections
       IndexWriter.sections(examples, @configuration)
     end

data/lib/rspec_api_documentation/oauth2_mac_client.rb

@@ -42,8 +42,8 @@ module RspecApiDocumentation
 
     protected
 
-    def do_request(method, path, params)
-      self.last_response = access_token.send(method, "http://example.com#{path}", :body => params, :header => headers(method, path, params))
+    def do_request(method, path, params, request_headers)
+      self.last_response = access_token.send(method, "http://example.com#{path}", :body => params, :header => headers(method, path, params, request_headers))
     end
 
     class ProxyApp < Struct.new(:client, :app)

data/lib/rspec_api_documentation/rack_test_client.rb

@@ -34,8 +34,12 @@ module RspecApiDocumentation
 
     protected
 
-    def do_request(method, path, params)
-      rack_test_session.send(method, path, params, headers(method, path, params))
+    def do_request(method, path, params, request_headers)
+      rack_test_session.send(method, path, params, headers(method, path, params, request_headers))
+    end
+
+    def headers(*args)
+      headers_to_env(super)
     end
 
     private

data/lib/rspec_api_documentation/wurl_writer.rb

@@ -35,6 +35,10 @@ module RspecApiDocumentation
       self.template_path = configuration.template_path
     end
 
+    def api_name
+      @configuration.api_name
+    end
+
     def sections
       IndexWriter.sections(examples, @configuration)
     end

data/lib/rspec_api_documentation.rb

@@ -28,6 +28,8 @@ module RspecApiDocumentation
   autoload :WurlWriter
   autoload :JsonWriter
   autoload :IndexWriter
+  autoload :CombinedTextWriter
+  autoload :CombinedJsonWriter
   autoload :Curl
 
   def self.configuration

data/lib/tasks/docs.rake

@@ -1,9 +1,7 @@
 require 'rspec/core/rake_task'
 
-if Rails.env.test? || Rails.env.development?
-  desc 'Generate API request documentation from API specs'
-  RSpec::Core::RakeTask.new('docs:generate') do |t|
-    t.pattern = 'spec/acceptance/**/*_spec.rb'
-    t.rspec_opts = ["--format RspecApiDocumentation::ApiFormatter"]
-  end
+desc 'Generate API request documentation from API specs'
+RSpec::Core::RakeTask.new('docs:generate') do |t|
+  t.pattern = 'spec/acceptance/**/*_spec.rb'
+  t.rspec_opts = ["--format RspecApiDocumentation::ApiFormatter"]
 end

data/templates/rspec_api_documentation/html_example.mustache

@@ -2,15 +2,15 @@
 <html>
   <head>
     <title>{{resource_name}} API</title>
-    <link rel="stylesheet" href="/{{url_prefix}}/assets/stylesheets/bootstrap.css"/>
-    <link rel="stylesheet" href="/{{url_prefix}}/assets/stylesheets/codemirror.css"/>
-    <link rel="stylesheet" href="/{{url_prefix}}/assets/stylesheets/application.css"/>
-    <script src="/{{url_prefix}}/assets/javascripts/jquery-1-7-2.js"></script>
-    <script src="/{{url_prefix}}/assets/javascripts/codemirror.js"></script>
-    <script src="/{{url_prefix}}/assets/javascripts/mode/css/css.js"></script>
-    <script src="/{{url_prefix}}/assets/javascripts/mode/htmlmixed/htmlmixed.js"></script>
-    <script src="/{{url_prefix}}/assets/javascripts/mode/javascript/javascript.js"></script>
-    <script src="/{{url_prefix}}/assets/javascripts/mode/xml/xml.js"></script>
+    <link rel="stylesheet" href="{{url_prefix}}/assets/stylesheets/bootstrap.css"/>
+    <link rel="stylesheet" href="{{url_prefix}}/assets/stylesheets/codemirror.css"/>
+    <link rel="stylesheet" href="{{url_prefix}}/assets/stylesheets/application.css"/>
+    <script src="{{url_prefix}}/assets/javascripts/jquery-1-7-2.js"></script>
+    <script src="{{url_prefix}}/assets/javascripts/codemirror.js"></script>
+    <script src="{{url_prefix}}/assets/javascripts/mode/css/css.js"></script>
+    <script src="{{url_prefix}}/assets/javascripts/mode/htmlmixed/htmlmixed.js"></script>
+    <script src="{{url_prefix}}/assets/javascripts/mode/javascript/javascript.js"></script>
+    <script src="{{url_prefix}}/assets/javascripts/mode/xml/xml.js"></script>
     <script>
       function mirror(textarea, contentType, options) {
         $textarea = $(textarea);
@@ -108,7 +108,7 @@
 
           {{# request_body }}
             <h4>Body</h4>
-            <div class="request body" data-content-type="{{ response_content_type }}"><textarea>{{{ request_body }}}</textarea></div>
+            <div class="request body" data-content-type="{{ request_content_type }}"><textarea>{{{ request_body }}}</textarea></div>
           {{/ request_body }}
 
           {{# curl }}
@@ -124,7 +124,7 @@
             <pre class="response status">{{ response_status }} {{ response_status_text}}</pre>
             {{# response_body }}
               <h4>Body</h4>
-              <div class="response body" data-content-type="{{ request_content_type }}"><textarea>{{{ response_body }}}</textarea></div>
+              <div class="response body" data-content-type="{{ response_content_type }}"><textarea>{{{ response_body }}}</textarea></div>
             {{/ response_body }}
           {{/ response_status }}
         {{/ requests }}

data/templates/rspec_api_documentation/html_index.mustache

@@ -1,12 +1,12 @@
 <!DOCTYPE html>
 <html>
 <head>
-  <title>API Documentation</title>
-  <link rel="stylesheet" href="/{{ url_prefix }}/assets/stylesheets/bootstrap.css"/>
+  <title>{{ api_name }}</title>
+  <link rel="stylesheet" href="{{ url_prefix }}/assets/stylesheets/bootstrap.css"/>
 </head>
 <body>
 <div class="container">
-  <h1>API Documentation</h1>
+  <h1>{{ api_name }}</h1>
 
   {{# sections }}
   <div class="article">
@@ -15,7 +15,7 @@
     <ul>
       {{# examples }}
       <li>
-        <a href="/{{ url_prefix }}{{ dirname }}/{{ filename }}">{{ description }}</a>
+        <a href="{{ url_prefix }}/{{ dirname }}/{{ filename }}">{{ description }}</a>
       </li>
       {{/ examples }}
     </ul>

data/templates/rspec_api_documentation/wurl_example.mustache

@@ -1,19 +1,19 @@
 <!DOCTYPE html>
 <head>
   <title>{{resource_name}} API</title>
-  <link rel="stylesheet" href="/{{url_prefix}}/assets/stylesheets/bootstrap.css"/>
-  <link rel="stylesheet" href="/{{url_prefix}}/assets/stylesheets/codemirror.css"/>
-  <link rel="stylesheet" href="/{{url_prefix}}/assets/stylesheets/application.css"/>
-  <script src="/{{url_prefix}}/assets/javascripts/jquery-1-7-2.js"></script>
-  <script src="/{{url_prefix}}/assets/javascripts/jquery-livequery.js"></script>
-  <script src="/{{url_prefix}}/assets/javascripts/jquery-base64.js"></script>
-  <script src="/{{url_prefix}}/assets/javascripts/jquery-ui-1-8-16-min.js"></script>
-  <script src="/{{url_prefix}}/assets/javascripts/codemirror.js"></script>
-  <script src="/{{url_prefix}}/assets/javascripts/mode/css/css.js"></script>
-  <script src="/{{url_prefix}}/assets/javascripts/mode/htmlmixed/htmlmixed.js"></script>
-  <script src="/{{url_prefix}}/assets/javascripts/mode/javascript/javascript.js"></script>
-  <script src="/{{url_prefix}}/assets/javascripts/mode/xml/xml.js"></script>
-  <script src="/{{url_prefix}}/assets/javascripts/application.js"></script>
+  <link rel="stylesheet" href="{{url_prefix}}/assets/stylesheets/bootstrap.css"/>
+  <link rel="stylesheet" href="{{url_prefix}}/assets/stylesheets/codemirror.css"/>
+  <link rel="stylesheet" href="{{url_prefix}}/assets/stylesheets/application.css"/>
+  <script src="{{url_prefix}}/assets/javascripts/jquery-1-7-2.js"></script>
+  <script src="{{url_prefix}}/assets/javascripts/jquery-livequery.js"></script>
+  <script src="{{url_prefix}}/assets/javascripts/jquery-base64.js"></script>
+  <script src="{{url_prefix}}/assets/javascripts/jquery-ui-1-8-16-min.js"></script>
+  <script src="{{url_prefix}}/assets/javascripts/codemirror.js"></script>
+  <script src="{{url_prefix}}/assets/javascripts/mode/css/css.js"></script>
+  <script src="{{url_prefix}}/assets/javascripts/mode/htmlmixed/htmlmixed.js"></script>
+  <script src="{{url_prefix}}/assets/javascripts/mode/javascript/javascript.js"></script>
+  <script src="{{url_prefix}}/assets/javascripts/mode/xml/xml.js"></script>
+  <script src="{{url_prefix}}/assets/javascripts/application.js"></script>
   <script>
 
   </script>
@@ -238,4 +238,4 @@
 </div>
 </div>
 </body>
-</html>
+</html>

data/templates/rspec_api_documentation/wurl_index.mustache

@@ -1,12 +1,12 @@
 <!DOCTYPE html>
 <html>
 <head>
-  <title>API Documentation</title>
-  <link rel="stylesheet" href="/{{ url_prefix }}/assets/stylesheets/bootstrap.css"/>
+  <title>{{ api_name }}</title>
+  <link rel="stylesheet" href="{{ url_prefix }}/assets/stylesheets/bootstrap.css"/>
 </head>
 <body>
 <div class="container">
-  <h1>API Documentation</h1>
+  <h1>{{ api_name }}</h1>
 
   {{# sections }}
   <div class="article">
@@ -15,7 +15,7 @@
     <ul>
       {{# examples }}
       <li>
-        <a href="/{{ url_prefix }}{{ dirname }}/{{ filename }}">{{ description }}</a>
+        <a href="{{ url_prefix }}/{{ dirname }}/{{ filename }}">{{ description }}</a>
       </li>
       {{/ examples }}
     </ul>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec_api_documentation
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
   prerelease: 
 platform: ruby
 authors:
@@ -11,11 +11,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-21 00:00:00.000000000Z
+date: 2012-07-03 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70239312431960 !ruby/object:Gem::Requirement
+  requirement: &70135105134860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -23,10 +23,10 @@ dependencies:
         version: 2.6.0
   type: :runtime
   prerelease: false
-  version_requirements: *70239312431960
+  version_requirements: *70135105134860
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70239312430760 !ruby/object:Gem::Requirement
+  requirement: &70135105133960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -34,10 +34,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *70239312430760
+  version_requirements: *70135105133960
 - !ruby/object:Gem::Dependency
   name: i18n
-  requirement: &70239312429680 !ruby/object:Gem::Requirement
+  requirement: &70135105132820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -45,10 +45,10 @@ dependencies:
         version: 0.1.0
   type: :runtime
   prerelease: false
-  version_requirements: *70239312429680
+  version_requirements: *70135105132820
 - !ruby/object:Gem::Dependency
   name: mustache
-  requirement: &70239312428600 !ruby/object:Gem::Requirement
+  requirement: &70135105131980 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -56,10 +56,10 @@ dependencies:
         version: 0.99.4
   type: :runtime
   prerelease: false
-  version_requirements: *70239312428600
+  version_requirements: *70135105131980
 - !ruby/object:Gem::Dependency
   name: webmock
-  requirement: &70239312427680 !ruby/object:Gem::Requirement
+  requirement: &70135105130500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -67,10 +67,10 @@ dependencies:
         version: 1.7.0
   type: :runtime
   prerelease: false
-  version_requirements: *70239312427680
+  version_requirements: *70135105130500
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &70239312426980 !ruby/object:Gem::Requirement
+  requirement: &70135105129420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -78,10 +78,10 @@ dependencies:
         version: 1.4.6
   type: :runtime
   prerelease: false
-  version_requirements: *70239312426980
+  version_requirements: *70135105129420
 - !ruby/object:Gem::Dependency
   name: fakefs
-  requirement: &70239312426260 !ruby/object:Gem::Requirement
+  requirement: &70135105128660 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -89,10 +89,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70239312426260
+  version_requirements: *70135105128660
 - !ruby/object:Gem::Dependency
   name: sinatra
-  requirement: &70239312425460 !ruby/object:Gem::Requirement
+  requirement: &70135105127860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -100,10 +100,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70239312425460
+  version_requirements: *70135105127860
 - !ruby/object:Gem::Dependency
   name: aruba
-  requirement: &70239312424480 !ruby/object:Gem::Requirement
+  requirement: &70135105115500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -111,10 +111,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70239312424480
+  version_requirements: *70135105115500
 - !ruby/object:Gem::Dependency
   name: capybara
-  requirement: &70239312411060 !ruby/object:Gem::Requirement
+  requirement: &70135105114560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -122,10 +122,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70239312411060
+  version_requirements: *70135105114560
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70239312410480 !ruby/object:Gem::Requirement
+  requirement: &70135105112420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -133,10 +133,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70239312410480
+  version_requirements: *70135105112420
 - !ruby/object:Gem::Dependency
   name: rack-test
-  requirement: &70239312409580 !ruby/object:Gem::Requirement
+  requirement: &70135105111420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -144,10 +144,10 @@ dependencies:
         version: 0.5.5
   type: :development
   prerelease: false
-  version_requirements: *70239312409580
+  version_requirements: *70135105111420
 - !ruby/object:Gem::Dependency
   name: rack-oauth2
-  requirement: &70239312408200 !ruby/object:Gem::Requirement
+  requirement: &70135105110060 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -155,7 +155,7 @@ dependencies:
         version: 0.14.4
   type: :development
   prerelease: false
-  version_requirements: *70239312408200
+  version_requirements: *70135105110060
 description: Generate API docs from your test suite
 email:
 - chris@smartlogicsolutions.com
@@ -168,6 +168,8 @@ files:
 - lib/rspec_api_documentation/api_documentation.rb
 - lib/rspec_api_documentation/api_formatter.rb
 - lib/rspec_api_documentation/client_base.rb
+- lib/rspec_api_documentation/combined_json_writer.rb
+- lib/rspec_api_documentation/combined_text_writer.rb
 - lib/rspec_api_documentation/configuration.rb
 - lib/rspec_api_documentation/curl.rb
 - lib/rspec_api_documentation/dsl/callback.rb