rspec_api_documentation 0.9.2 → 1.0.0

data/lib/rspec_api_documentation.rb

@@ -14,7 +14,6 @@ module RspecApiDocumentation
     autoload :ApiDocumentation
     autoload :ApiFormatter
     autoload :Example
-    autoload :ExampleGroup
     autoload :Index
     autoload :ClientBase
     autoload :Headers
@@ -24,15 +23,19 @@ module RspecApiDocumentation
   autoload :RackTestClient
   autoload :OAuth2MACClient, "rspec_api_documentation/oauth2_mac_client"
   autoload :TestServer
-  autoload :HtmlWriter
-  autoload :WurlWriter
-  autoload :JsonWriter
-  autoload :JsonIodocsWriter
-  autoload :IndexWriter
-  autoload :CombinedTextWriter
-  autoload :CombinedJsonWriter
   autoload :Curl
 
+  module Writers
+    extend ActiveSupport::Autoload
+
+    autoload :HtmlWriter
+    autoload :JsonWriter
+    autoload :JsonIodocsWriter
+    autoload :IndexWriter
+    autoload :CombinedTextWriter
+    autoload :CombinedJsonWriter
+  end
+
   def self.configuration
     @configuration ||= Configuration.new
   end

data/lib/rspec_api_documentation/api_documentation.rb

@@ -14,7 +14,6 @@ module RspecApiDocumentation
         FileUtils.rm_rf(docs_dir, :secure => true)
       end
       FileUtils.mkdir_p(docs_dir)
-      FileUtils.cp_r(File.join(configuration.template_path, "assets"), docs_dir)
     end
 
     def document_example(rspec_example)
@@ -32,7 +31,7 @@ module RspecApiDocumentation
 
     def writers
       [*configuration.format].map do |format|
-        RspecApiDocumentation.const_get("#{format}_writer".classify)
+        RspecApiDocumentation::Writers.const_get("#{format}_writer".classify)
       end
     end
   end

data/lib/rspec_api_documentation/configuration.rb

@@ -17,7 +17,6 @@ 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
@@ -47,7 +46,6 @@ module RspecApiDocumentation
     add_setting :template_path, :default => File.expand_path("../../../templates", __FILE__)
     add_setting :filter, :default => :all
     add_setting :exclusion_filter, :default => nil
-    add_setting :url_prefix, :default => ""
     add_setting :app, :default => lambda { |config|
       if defined?(Rails)
         Rails.application

data/lib/rspec_api_documentation/curl.rb

@@ -39,7 +39,7 @@ module RspecApiDocumentation
 
     def headers
       super.map do |k, v|
-        "-H \"#{format_header(k, v)}\""
+        "\\\n\t-H \"#{format_header(k, v)}\""
       end.join(" ")
     end
 

data/lib/rspec_api_documentation/example.rb

@@ -25,9 +25,9 @@ module RspecApiDocumentation
 
     def should_document?
       return false if pending? || !metadata[:resource_name] || !metadata[:document]
-      return true if configuration.filter == :all
       return false if (Array(metadata[:document]) & Array(configuration.exclusion_filter)).length > 0
       return true if (Array(metadata[:document]) & Array(configuration.filter)).length > 0
+      return true if configuration.filter == :all
     end
 
     def public?

data/lib/rspec_api_documentation/writers/combined_json_writer.rb

@@ -0,0 +1,20 @@
+require 'rspec_api_documentation/writers/json_writer'
+
+module RspecApiDocumentation
+  module Writers
+    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 << Formatter.to_json(JsonExample.new(rspec_example, configuration))
+          end
+
+          f.write "["
+          f.write examples.join(",")
+          f.write "]"
+        end
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/writers/combined_text_writer.rb

@@ -0,0 +1,106 @@
+module RspecApiDocumentation
+  module Writers
+    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_with_index do |(request, response), i|
+              f.puts "Request:"
+              f.puts request
+              f.puts
+              f.puts "Response:"
+              f.puts response
+
+              if i + 1 < example.requests.count
+                f.puts
+              end
+            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
+end

data/lib/rspec_api_documentation/writers/formatter.rb

@@ -0,0 +1,11 @@
+module RspecApiDocumentation
+  module Writers
+    module Formatter
+
+      def self.to_json(object)
+        JSON.pretty_generate(object.as_json)
+      end
+
+    end
+  end
+end

data/lib/rspec_api_documentation/writers/html_writer.rb

@@ -0,0 +1,102 @@
+require 'mustache'
+
+module RspecApiDocumentation
+  module Writers
+    class HtmlWriter
+      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
+
+      def filename
+        basename = description.downcase.gsub(/\s+/, '_').gsub(/[^a-z_]/, '')
+        basename = Digest::MD5.new.update(description).to_s if basename.blank?
+        "#{basename}.html"
+      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
+
+      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/writers/index_writer.rb

@@ -0,0 +1,16 @@
+require "active_support/core_ext/enumerable"
+
+module RspecApiDocumentation
+  module Writers
+    module IndexWriter
+      def sections(examples, configuration)
+        resources = examples.group_by(&:resource_name).inject([]) do |arr, (resource_name, examples)|
+          ordered_examples = configuration.keep_source_order ? examples : examples.sort_by(&:description)
+          arr.push(:resource_name => resource_name, :examples => ordered_examples)
+        end
+        configuration.keep_source_order ? resources : resources.sort_by { |resource| resource[:resource_name] }
+      end
+      module_function :sections
+    end
+  end
+end

data/lib/rspec_api_documentation/writers/json_iodocs_writer.rb

@@ -0,0 +1,111 @@
+require 'rspec_api_documentation/writers/formatter'
+
+module RspecApiDocumentation
+  module Writers
+    class JsonIodocsWriter
+      attr_accessor :index, :configuration, :api_key
+      delegate :docs_dir, :to => :configuration
+
+      def initialize(index, configuration)
+        self.index = index
+        self.configuration = configuration
+        self.api_key = configuration.api_name.parameterize
+      end
+
+      def self.write(index, configuration)
+        writer = new(index, configuration)
+        writer.write
+      end
+
+      def write
+        File.open(docs_dir.join("apiconfig.json"), "w+") do |file|
+          file.write Formatter.to_json(ApiConfig.new(configuration))
+        end
+        File.open(docs_dir.join("#{api_key}.json"), "w+") do |file|
+          file.write Formatter.to_json(JsonIndex.new(index, configuration))
+        end
+      end
+    end
+
+    class JsonIndex
+      def initialize(index, configuration)
+        @index = index
+        @configuration = configuration
+      end
+
+      def sections
+        IndexWriter.sections(examples, @configuration)
+      end
+
+      def examples
+        @index.examples.map { |example| JsonExample.new(example, @configuration) }
+      end
+
+      def as_json(opts = nil)
+        sections.inject({:endpoints => []}) do |h, section|
+          h[:endpoints].push(
+            :name => section[:resource_name],
+            :methods => section[:examples].map do |example|
+              example.as_json(opts)
+            end
+          )
+          h
+        end
+      end
+    end
+
+    class JsonExample
+      def initialize(example, configuration)
+        @example = example
+      end
+
+      def method_missing(method, *args, &block)
+        @example.send(method, *args, &block)
+      end
+
+      def parameters
+        params = []
+        if @example.respond_to?(:parameters)
+          @example.parameters.map do |param|
+            params << {
+              "Name" => param[:name],
+              "Description" => param[:description],
+              "Default" => "",
+              "Required" => param[:required] ? "Y" : "N"
+            }
+          end
+        end
+        params
+      end
+
+      def as_json(opts = nil)
+         {
+          :MethodName => description,
+          :Synopsis => explanation,
+          :HTTPMethod => http_method,
+          :URI => (requests.first[:request_path] rescue ""),
+          :RequiresOAuth => "N",
+          :parameters => parameters
+        }
+      end
+    end
+
+    class ApiConfig
+      def initialize(configuration)
+        @configuration = configuration
+        @api_key = configuration.api_name.parameterize
+      end
+
+      def as_json(opts = nil)
+        {
+          @api_key.to_sym => {
+            :name => @configuration.api_name,
+            :protocol => "http",
+            :publicPath => "",
+            :baseURL => @configuration.curl_host
+          }
+        }
+      end
+    end
+  end
+end