rspec_api_documentation 1.1.0 → 2.0.0

data/lib/rspec_api_documentation.rb

@@ -28,7 +28,9 @@ module RspecApiDocumentation
   module Writers
     extend ActiveSupport::Autoload
 
+    autoload :GeneralMarkupWriter
     autoload :HtmlWriter
+    autoload :TextileWriter
     autoload :JsonWriter
     autoload :JsonIodocsWriter
     autoload :IndexWriter
@@ -36,6 +38,17 @@ module RspecApiDocumentation
     autoload :CombinedJsonWriter
   end
 
+  module Views
+    extend ActiveSupport::Autoload
+
+    autoload :MarkupIndex
+    autoload :MarkupExample
+    autoload :HtmlIndex
+    autoload :HtmlExample
+    autoload :TextileIndex
+    autoload :TextileExample
+  end
+
   def self.configuration
     @configuration ||= Configuration.new
   end

data/lib/rspec_api_documentation/configuration.rb

@@ -57,6 +57,20 @@ module RspecApiDocumentation
     add_setting :curl_host, :default => nil
     add_setting :keep_source_order, :default => false
     add_setting :api_name, :default => "API Documentation"
+    add_setting :io_docs_protocol, :default => "http"
+
+    def client_method=(new_client_method)
+      RspecApiDocumentation::DSL::Resource.module_eval <<-RUBY
+        alias :#{new_client_method} #{client_method}
+        undef #{client_method}
+      RUBY
+
+      @client_method = new_client_method
+    end
+
+    def client_method
+      @client_method ||= :client
+    end
 
     def settings
       @settings ||= {}

data/lib/rspec_api_documentation/dsl/endpoint.rb

@@ -7,7 +7,7 @@ module RspecApiDocumentation::DSL
     extend ActiveSupport::Concern
     include Rack::Test::Utils
 
-    delegate :response_headers, :status, :response_status, :response_body, :to => :client
+    delegate :response_headers, :status, :response_status, :response_body, :to => :rspec_api_documentation_client
 
     module ClassMethods
       def example_request(description, params = {}, &block)
@@ -44,7 +44,7 @@ module RspecApiDocumentation::DSL
         params_or_body = respond_to?(:raw_post) ? raw_post : params
       end
 
-      client.send(method, path_or_query, params_or_body, headers)
+      rspec_api_documentation_client.send(method, path_or_query, params_or_body, headers)
     end
 
     def query_string
@@ -52,14 +52,18 @@ module RspecApiDocumentation::DSL
     end
 
     def params
-      return unless example.metadata[:parameters]
-      parameters = example.metadata[:parameters].inject({}) do |hash, param|
+      parameters = example.metadata.fetch(:parameters, {}).inject({}) do |hash, param|
         set_param(hash, param)
       end
       parameters.merge!(extra_params)
       parameters
     end
 
+    def header(name, value)
+      example.metadata[:headers] ||= {}
+      example.metadata[:headers][name] = value
+    end
+
     def headers
       return unless example.metadata[:headers]
       example.metadata[:headers].inject({}) do |hash, (header, value)|
@@ -101,6 +105,11 @@ module RspecApiDocumentation::DSL
     end
 
     private
+
+    def rspec_api_documentation_client
+      send(RspecApiDocumentation.configuration.client_method)
+    end
+
     def extra_params
       return {} if @extra_params.nil?
       @extra_params.inject({}) do |h, (k, v)|

data/lib/rspec_api_documentation/dsl/resource.rb

@@ -41,33 +41,6 @@ module RspecApiDocumentation::DSL
         headers[name] = value
       end
 
-      def required_parameters(*names)
-        warn "required_parameters is no longer supported. Please use parameter :name, '', :required => true instead."
-
-        names.each do |name|
-          param = parameters.find { |param| param[:name] == name.to_s }
-          raise "Undefined parameters can not be required." unless param
-          param[:required] = true
-        end
-      end
-
-      def scope_parameters(scope, keys)
-        warn "scope_paramters is no longer supported. Please use parameter :name, '', :scope => 'scope' instead."
-
-        return unless metadata[:parameters]
-
-        if keys == :all
-          keys = parameter_keys.map(&:to_s)
-        else
-          keys = keys.map(&:to_s)
-        end
-
-        keys.each do |key|
-          param = parameters.detect { |param| param[:name] == key }
-          param[:scope] = scope if param
-        end
-      end
-
       private
       def parameters
         metadata[:parameters] ||= []

data/lib/rspec_api_documentation/views/html_example.rb

@@ -0,0 +1,16 @@
+module RspecApiDocumentation
+  module Views
+    class HtmlExample < MarkupExample
+      EXTENSION = 'html'
+
+      def initialize(example, configuration)
+        super
+        self.template_name = "rspec_api_documentation/html_example"
+      end
+
+      def extension
+        EXTENSION
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/views/html_index.rb

@@ -0,0 +1,14 @@
+module RspecApiDocumentation
+  module Views
+    class HtmlIndex < MarkupIndex
+      def initialize(index, configuration)
+        super
+        self.template_name = "rspec_api_documentation/html_index"
+      end
+      
+      def examples
+        @index.examples.map { |example| HtmlExample.new(example, @configuration) }
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/views/markup_example.rb

@@ -0,0 +1,58 @@
+require 'mustache'
+
+module RspecApiDocumentation
+  module Views
+    class MarkupExample < Mustache
+      def initialize(example, configuration)
+        @example = example
+        @host = configuration.curl_host
+        self.template_path = configuration.template_path
+      end
+      
+      def method_missing(method, *args, &block)
+        @example.send(method, *args, &block)
+      end
+
+      def respond_to?(method, include_private = false)
+        super || @example.respond_to?(method, include_private)
+      end
+
+      def dirname
+        resource_name.downcase.gsub(/\s+/, '_')
+      end
+      
+      def filename
+        basename = description.downcase.gsub(/\s+/, '_').gsub(/[^a-z_]/, '')
+        basename = Digest::MD5.new.update(description).to_s if basename.blank?
+        "#{basename}.#{extension}"
+      end
+      
+      def requests
+        super.map do |hash|
+          hash[:request_headers_text] = format_hash(hash[:request_headers])
+          hash[:request_query_parameters_text] = format_hash(hash[:request_query_parameters])
+          hash[:response_headers_text] = format_hash(hash[:response_headers])
+          if @host
+            hash[:curl] = hash[:curl].output(@host) if hash[:curl].is_a? RspecApiDocumentation::Curl
+          else
+            hash[:curl] = nil
+          end
+          hash
+        end
+      end
+      
+      def extension
+        raise 'Parent class. This method should not be called.'
+      end
+
+      private
+
+      def format_hash(hash = {})
+        return nil unless hash.present?
+        hash.collect do |k, v|
+          "#{k}: #{v}"
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/views/markup_index.rb

@@ -0,0 +1,21 @@
+require 'mustache'
+
+module RspecApiDocumentation
+  module Views
+    class MarkupIndex < Mustache
+      def initialize(index, configuration)
+        @index = index
+        @configuration = configuration
+        self.template_path = configuration.template_path
+      end
+      
+      def api_name
+        @configuration.api_name
+      end
+
+      def sections
+        RspecApiDocumentation::Writers::IndexWriter.sections(examples, @configuration)
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/views/textile_example.rb

@@ -0,0 +1,16 @@
+module RspecApiDocumentation
+  module Views
+    class TextileExample < MarkupExample
+      EXTENSION = 'textile'
+
+      def initialize(example, configuration)
+        super
+        self.template_name = "rspec_api_documentation/textile_example"
+      end
+
+      def extension
+        EXTENSION
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/views/textile_index.rb

@@ -0,0 +1,14 @@
+module RspecApiDocumentation
+  module Views
+    class TextileIndex < MarkupIndex
+      def initialize(index, configuration)
+        super
+        self.template_name = "rspec_api_documentation/textile_index"
+      end
+      
+      def examples
+        @index.examples.map { |example| TextileExample.new(example, @configuration) }
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/writers/general_markup_writer.rb

@@ -0,0 +1,42 @@
+module RspecApiDocumentation
+  module Writers
+    class GeneralMarkupWriter
+      attr_accessor :index, :configuration
+
+      INDEX_FILE_NAME = 'index'
+      
+      def initialize(index, configuration)
+        self.index = index
+        self.configuration = configuration
+      end
+
+      def self.write(index, configuration)
+        writer = new(index, configuration)
+        writer.write
+      end
+      
+      def write
+        File.open(configuration.docs_dir.join(index_file_name + '.' + extension), "w+") do |f|
+          f.write markup_index_class.new(index, configuration).render
+        end
+
+        index.examples.each do |example|
+          markup_example = markup_example_class.new(example, configuration)
+          FileUtils.mkdir_p(configuration.docs_dir.join(markup_example.dirname))
+
+          File.open(configuration.docs_dir.join(markup_example.dirname, markup_example.filename), "w+") do |f|
+            f.write markup_example.render
+          end
+        end
+      end
+
+      def index_file_name
+        INDEX_FILE_NAME
+      end
+
+      def extension
+        raise 'Parent class. This method should not be called.'
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/writers/html_writer.rb

@@ -1,101 +1,20 @@
-require 'mustache'
-
 module RspecApiDocumentation
   module Writers
-    class HtmlWriter
+    class HtmlWriter < GeneralMarkupWriter
       attr_accessor :index, :configuration
 
-      def initialize(index, configuration)
-        self.index = index
-        self.configuration = configuration
-      end
-
-      def self.write(index, configuration)
-        writer = new(index, configuration)
-        writer.write
-      end
-
-      def write
-        File.open(configuration.docs_dir.join("index.html"), "w+") do |f|
-          f.write HtmlIndex.new(index, configuration).render
-        end
-        index.examples.each do |example|
-          html_example = HtmlExample.new(example, configuration)
-          FileUtils.mkdir_p(configuration.docs_dir.join(html_example.dirname))
-          File.open(configuration.docs_dir.join(html_example.dirname, html_example.filename), "w+") do |f|
-            f.write html_example.render
-          end
-        end
-      end
-    end
-
-    class HtmlIndex < Mustache
-      def initialize(index, configuration)
-        @index = index
-        @configuration = configuration
-        self.template_path = configuration.template_path
-        self.template_name = "rspec_api_documentation/html_index"
-      end
-
-      def api_name
-        @configuration.api_name
-      end
-
-      def sections
-        IndexWriter.sections(examples, @configuration)
-      end
-
-      def examples
-        @index.examples.map { |example| HtmlExample.new(example, @configuration) }
-      end
-    end
-
-    class HtmlExample < Mustache
-      def initialize(example, configuration)
-        @example = example
-        @host = configuration.curl_host
-        self.template_path = configuration.template_path
-        self.template_name = "rspec_api_documentation/html_example"
-      end
-
-      def method_missing(method, *args, &block)
-        @example.send(method, *args, &block)
-      end
-
-      def respond_to?(method, include_private = false)
-        super || @example.respond_to?(method, include_private)
-      end
-
-      def dirname
-        resource_name.downcase.gsub(/\s+/, '_')
-      end
+      EXTENSION = 'html'
 
-      def filename
-        basename = description.downcase.gsub(/\s+/, '_').gsub(/[^a-z_]/, '')
-        basename = Digest::MD5.new.update(description).to_s if basename.blank?
-        "#{basename}.html"
+      def markup_index_class
+        RspecApiDocumentation::Views::HtmlIndex
       end
 
-      def requests
-        super.map do |hash|
-          hash[:request_headers_text] = format_hash(hash[:request_headers])
-          hash[:request_query_parameters_text] = format_hash(hash[:request_query_parameters])
-          hash[:response_headers_text] = format_hash(hash[:response_headers])
-          if @host
-            hash[:curl] = hash[:curl].output(@host) if hash[:curl].is_a? RspecApiDocumentation::Curl
-          else
-            hash[:curl] = nil
-          end
-          hash
-        end
+      def markup_example_class
+        RspecApiDocumentation::Views::HtmlExample
       end
 
-      private
-      def format_hash(hash = {})
-        return nil unless hash.present?
-        hash.collect do |k, v|
-          "#{k}: #{v}"
-        end.join("\n")
+      def extension
+        EXTENSION
       end
     end
   end

data/lib/rspec_api_documentation/writers/json_iodocs_writer.rb

@@ -100,7 +100,7 @@ module RspecApiDocumentation
         {
           @api_key.to_sym => {
             :name => @configuration.api_name,
-            :protocol => "http",
+            :protocol => @configuration.io_docs_protocol,
             :publicPath => "",
             :baseURL => @configuration.curl_host
           }

data/lib/rspec_api_documentation/writers/textile_writer.rb

@@ -0,0 +1,21 @@
+module RspecApiDocumentation
+  module Writers
+    class TextileWriter < GeneralMarkupWriter
+      attr_accessor :index, :configuration
+
+      EXTENSION = 'textile'
+
+      def markup_index_class
+        RspecApiDocumentation::Views::TextileIndex
+      end
+
+      def markup_example_class
+        RspecApiDocumentation::Views::TextileExample
+      end
+
+      def extension
+        EXTENSION
+      end
+    end
+  end
+end

data/templates/rspec_api_documentation/textile_example.mustache

@@ -0,0 +1,68 @@
+h1. {{ resource_name }} API
+
+h2. {{ description }}
+
+h3. {{ http_method }} {{ route }}
+
+{{# explanation }}
+{{ explanation }}
+{{/ explanation }}
+
+{{# has_parameters? }}
+h3. Parameters
+{{# parameters }}
+
+Name : {{ name }} {{# required }} *- required -*{{/ required }}
+Description : {{ description }}
+{{/ parameters }}
+{{/ has_parameters? }}
+
+{{# requests }}
+h3. Request
+
+h4. Headers
+
+<pre>{{ request_headers_text }}</pre>
+
+h4. Route
+
+<pre>{{ request_method }} {{ request_path }}</pre>
+
+{{# request_query_parameters_text }}
+h4. Query Parameters
+
+<pre>{{ request_query_parameters_text }}</pre>
+{{/ request_query_parameters_text }}
+
+{{# request_body }}
+h4. Body
+
+<pre>{{{ request_body }}}</pre>
+{{/ request_body }}
+
+{{# curl }}
+h4. cURL
+
+<pre class="request">{{ curl }}</pre>
+{{/ curl }}
+
+{{# response_status }}
+h3. Response
+
+h4. Headers
+
+<pre>{{ response_headers_text }}</pre>
+
+h4. Status
+
+<pre>{{ response_status }} {{ response_status_text}}</pre>
+
+{{# response_body }}
+h4. Body
+
+<pre>{{{ response_body }}}</pre>
+{{/ response_body }}
+{{/ response_status }}
+
+{{/ requests }}
+

data/templates/rspec_api_documentation/textile_index.mustache

@@ -0,0 +1,10 @@
+h1. {{ api_name }}
+
+{{# sections }}
+h2. {{ resource_name }}
+
+{{# examples }}
+* "{{ description }}":{{ dirname }}/{{ filename }}
+{{/ examples }}
+
+{{/ sections }}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec_api_documentation
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-12 00:00:00.000000000 Z
+date: 2013-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -230,33 +230,43 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/rspec_api_documentation/api_documentation.rb
+- lib/rspec_api_documentation.rb
+- lib/tasks/docs.rake
+- lib/rspec_api_documentation/rack_test_client.rb
 - lib/rspec_api_documentation/api_formatter.rb
-- lib/rspec_api_documentation/client_base.rb
-- lib/rspec_api_documentation/configuration.rb
 - lib/rspec_api_documentation/curl.rb
+- lib/rspec_api_documentation/index.rb
+- lib/rspec_api_documentation/headers.rb
+- lib/rspec_api_documentation/oauth2_mac_client.rb
 - lib/rspec_api_documentation/dsl/callback.rb
 - lib/rspec_api_documentation/dsl/endpoint.rb
 - lib/rspec_api_documentation/dsl/resource.rb
 - lib/rspec_api_documentation/dsl.rb
-- lib/rspec_api_documentation/example.rb
-- lib/rspec_api_documentation/headers.rb
-- lib/rspec_api_documentation/index.rb
-- lib/rspec_api_documentation/oauth2_mac_client.rb
-- lib/rspec_api_documentation/rack_test_client.rb
-- lib/rspec_api_documentation/railtie.rb
-- lib/rspec_api_documentation/test_server.rb
-- lib/rspec_api_documentation/writers/combined_json_writer.rb
-- lib/rspec_api_documentation/writers/combined_text_writer.rb
-- lib/rspec_api_documentation/writers/formatter.rb
+- lib/rspec_api_documentation/views/html_example.rb
+- lib/rspec_api_documentation/views/html_index.rb
+- lib/rspec_api_documentation/views/textile_example.rb
+- lib/rspec_api_documentation/views/textile_index.rb
+- lib/rspec_api_documentation/views/markup_index.rb
+- lib/rspec_api_documentation/views/markup_example.rb
+- lib/rspec_api_documentation/writers/textile_writer.rb
+- lib/rspec_api_documentation/writers/general_markup_writer.rb
 - lib/rspec_api_documentation/writers/html_writer.rb
-- lib/rspec_api_documentation/writers/index_writer.rb
 - lib/rspec_api_documentation/writers/json_iodocs_writer.rb
 - lib/rspec_api_documentation/writers/json_writer.rb
-- lib/rspec_api_documentation.rb
-- lib/tasks/docs.rake
-- templates/rspec_api_documentation/html_example.mustache
+- lib/rspec_api_documentation/writers/combined_json_writer.rb
+- lib/rspec_api_documentation/writers/formatter.rb
+- lib/rspec_api_documentation/writers/index_writer.rb
+- lib/rspec_api_documentation/writers/combined_text_writer.rb
+- lib/rspec_api_documentation/configuration.rb
+- lib/rspec_api_documentation/example.rb
+- lib/rspec_api_documentation/api_documentation.rb
+- lib/rspec_api_documentation/test_server.rb
+- lib/rspec_api_documentation/railtie.rb
+- lib/rspec_api_documentation/client_base.rb
+- templates/rspec_api_documentation/textile_example.mustache
 - templates/rspec_api_documentation/html_index.mustache
+- templates/rspec_api_documentation/textile_index.mustache
+- templates/rspec_api_documentation/html_example.mustache
 homepage: http://smartlogicsolutions.com
 licenses: []
 post_install_message: