rspec-api-documentation 1.1.1.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7eaab971cec433522e7a0c8920b1bf3c37fee9f6
+  data.tar.gz: 9f0eb16b2fd3a70892e36f73d5e3d9e5c54fb738
+SHA512:
+  metadata.gz: a786afed2c20a213956ef0cface62a978e41fbea4943e1f0c2da94a1d7f001a470714e06ec17ba8e1598195b577d2dbc51fee24f99f7c835a002917e39d7db31
+  data.tar.gz: 15e97461f543a737d32e4a226e6b9e9384bda8fbec5c8f5c9af6c4991c9a105bb243c9a9480bd91d4dc0411511ce3d8d261e97084a8352c80e92bb025bd0442f

data/lib/rspec_api_documentation.rb

@@ -0,0 +1,63 @@
+require 'active_support'
+require 'active_support/inflector'
+require 'cgi'
+require 'json'
+
+module RspecApiDocumentation
+  extend ActiveSupport::Autoload
+
+  require 'rspec_api_documentation/railtie' if defined?(Rails)
+  include ActiveSupport::JSON
+
+  eager_autoload do
+    autoload :Configuration
+    autoload :ApiDocumentation
+    autoload :ApiFormatter
+    autoload :Example
+    autoload :Index
+    autoload :ClientBase
+    autoload :Headers
+  end
+
+  autoload :DSL
+  autoload :RackTestClient
+  autoload :OAuth2MACClient, "rspec_api_documentation/oauth2_mac_client"
+  autoload :TestServer
+  autoload :Curl
+
+  module Writers
+    extend ActiveSupport::Autoload
+
+    autoload :GeneralMarkupWriter
+    autoload :HtmlWriter
+    autoload :TextileWriter
+    autoload :JsonWriter
+    autoload :JsonIodocsWriter
+    autoload :IndexWriter
+    autoload :CombinedTextWriter
+    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
+
+  def self.documentations
+    @documentations ||= configuration.map { |config| ApiDocumentation.new(config) }
+  end
+
+  def self.configure
+    yield configuration if block_given?
+  end
+end

data/lib/rspec_api_documentation/api_documentation.rb

@@ -0,0 +1,38 @@
+module RspecApiDocumentation
+  class ApiDocumentation
+    attr_reader :configuration, :index
+
+    delegate :docs_dir, :format, :to => :configuration
+
+    def initialize(configuration)
+      @configuration = configuration
+      @index = Index.new
+    end
+
+    def clear_docs
+      if File.exists?(docs_dir)
+        FileUtils.rm_rf(docs_dir, :secure => true)
+      end
+      FileUtils.mkdir_p(docs_dir)
+    end
+
+    def document_example(rspec_example)
+      example = Example.new(rspec_example, configuration)
+      if example.should_document?
+        index.examples << example
+      end
+    end
+
+    def write
+      writers.each do |writer|
+        writer.write(index, configuration)
+      end
+    end
+
+    def writers
+      [*configuration.format].map do |format|
+        RspecApiDocumentation::Writers.const_get("#{format}_writer".classify)
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/api_formatter.rb

@@ -0,0 +1,45 @@
+require 'rspec/core/formatters/base_text_formatter'
+
+module RspecApiDocumentation
+  class ApiFormatter < RSpec::Core::Formatters::BaseTextFormatter
+    def initialize(output)
+      super
+
+      output.puts "Generating API Docs"
+    end
+
+    def start(example_count)
+      super
+
+      RspecApiDocumentation.documentations.each(&:clear_docs)
+    end
+
+    def example_group_started(example_group)
+      super
+
+      output.puts "  #{example_group.description}"
+    end
+
+    def example_passed(example)
+      super
+
+      output.puts "    * #{example.description}"
+
+      RspecApiDocumentation.documentations.each do |documentation|
+        documentation.document_example(example)
+      end
+    end
+
+    def example_failed(example)
+      super
+
+      output.puts "    ! #{example.description} (FAILED)"
+    end
+
+    def stop
+      super
+
+      RspecApiDocumentation.documentations.each(&:write)
+    end
+  end
+end

data/lib/rspec_api_documentation/client_base.rb

@@ -0,0 +1,82 @@
+module RspecApiDocumentation
+  class ClientBase < Struct.new(:context, :options)
+    include Headers
+
+    delegate :example, :app, :to => :context
+    delegate :metadata, :to => :example
+
+    def get(*args)
+      process :get, *args
+    end
+
+    def post(*args)
+      process :post, *args
+    end
+
+    def put(*args)
+      process :put, *args
+    end
+
+    def delete(*args)
+      process :delete, *args
+    end
+
+    def head(*args)
+      process :head, *args
+    end
+
+    def patch(*args)
+      process :patch, *args
+    end
+
+    def response_status
+      status
+    end
+
+    private
+
+    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)
+      return unless metadata[:document]
+
+      input = last_request.env["rack.input"]
+      input.rewind
+      request_body = input.read
+
+      request_metadata = {}
+
+      request_metadata[:request_method] = method
+      request_metadata[:request_path] = path
+      request_metadata[:request_body] = request_body.empty? ? nil : request_body
+      request_metadata[:request_headers] = request_headers
+      request_metadata[:request_query_parameters] = query_hash
+      request_metadata[:request_content_type] = request_content_type
+      request_metadata[:response_status] = status
+      request_metadata[:response_status_text] = Rack::Utils::HTTP_STATUS_CODES[status]
+      request_metadata[:response_body] = response_body.empty? ? nil : response_body
+      request_metadata[:response_headers] = response_headers
+      request_metadata[:response_content_type] = response_content_type
+      request_metadata[:curl] = Curl.new(method, path, request_body, request_headers)
+
+      metadata[:requests] ||= []
+      metadata[:requests] << request_metadata
+    end
+
+    def query_hash
+      strings = query_string.split("&")
+      arrays = strings.map do |segment|
+        k,v = segment.split("=")
+        [k, v && CGI.unescape(v)]
+      end
+      Hash[arrays]
+    end
+
+    def headers(method, path, params, request_headers)
+      request_headers || {}
+    end
+  end
+end

data/lib/rspec_api_documentation/configuration.rb

@@ -0,0 +1,84 @@
+module RspecApiDocumentation
+  class Configuration
+    include Enumerable
+
+    attr_reader :parent
+
+    def initialize(parent = nil)
+      @parent = parent
+      @settings = parent.settings.clone if parent
+    end
+
+    def groups
+      @groups ||= []
+    end
+
+    def define_group(name, &block)
+      subconfig = self.class.new(self)
+      subconfig.filter = name
+      subconfig.docs_dir = self.docs_dir.join(name.to_s)
+      yield subconfig
+      groups << subconfig
+    end
+
+    def self.add_setting(name, opts = {})
+      define_method("#{name}=") { |value| settings[name] = value }
+      define_method("#{name}") do
+        if settings.has_key?(name)
+          settings[name]
+        elsif opts[:default].respond_to?(:call)
+          opts[:default].call(self)
+        else
+          opts[:default]
+        end
+      end
+    end
+
+    add_setting :docs_dir, :default => lambda { |config|
+      if defined?(Rails)
+        Rails.root.join("doc", "api")
+      else
+        Pathname.new("doc/api")
+      end
+    }
+
+    add_setting :format, :default => :html
+    add_setting :template_path, :default => File.expand_path("../../../templates", __FILE__)
+    add_setting :filter, :default => :all
+    add_setting :exclusion_filter, :default => nil
+    add_setting :app, :default => lambda { |config|
+      if defined?(Rails)
+        Rails.application
+      else
+        nil
+      end
+    }
+
+    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 ||= {}
+    end
+
+    def each(&block)
+      yield self
+      groups.map { |g| g.each &block }
+    end
+  end
+end

data/lib/rspec_api_documentation/curl.rb

@@ -0,0 +1,61 @@
+require 'active_support/core_ext/object/to_query'
+
+module RspecApiDocumentation
+  class Curl < Struct.new(:method, :path, :data, :headers)
+    attr_accessor :host
+
+    def output(config_host)
+      self.host = config_host
+      send(method.downcase)
+    end
+
+    def post
+      "curl \"#{url}\" #{post_data} -X POST #{headers}"
+    end
+
+    def get
+      "curl \"#{url}#{get_data}\" -X GET #{headers}"
+    end
+
+    def put
+      "curl \"#{url}\" #{post_data} -X PUT #{headers}"
+    end
+
+    def delete
+      "curl \"#{url}\" #{post_data} -X DELETE #{headers}"
+    end
+
+    def head
+      "curl \"#{url}#{get_data}\" -X HEAD #{headers}"
+    end
+
+    def patch
+      "curl \"#{url}\" #{post_data} -X PATCH #{headers}"
+    end
+
+    def url
+      "#{host}#{path}"
+    end
+
+    def headers
+      super.map do |k, v|
+        "\\\n\t-H \"#{format_header(k, v)}\""
+      end.join(" ")
+    end
+
+    def get_data
+      "?#{data}" unless data.blank?
+    end
+
+    def post_data
+      escaped_data = data.to_s.gsub("'", "\\u0027")
+      "-d '#{escaped_data}'"
+    end
+
+    private
+    def format_header(header, value)
+      formatted_header = header.gsub(/^HTTP_/, '').titleize.split.join("-")
+      "#{formatted_header}: #{value}"
+    end
+  end
+end

data/lib/rspec_api_documentation/dsl.rb

@@ -0,0 +1,17 @@
+require "rspec_api_documentation/dsl/resource"
+require "rspec_api_documentation/dsl/endpoint"
+require "rspec_api_documentation/dsl/callback"
+
+def self.resource(*args, &block)
+  options = if args.last.is_a?(Hash) then args.pop else {} end
+  options[:api_doc_dsl] = :resource
+  options[:resource_name] = args.first
+  options[:document] ||= :all
+  args.push(options)
+  describe(*args, &block)
+end
+
+RSpec.configuration.include RspecApiDocumentation::DSL::Resource, :api_doc_dsl => :resource
+RSpec.configuration.include RspecApiDocumentation::DSL::Endpoint, :api_doc_dsl => :endpoint
+RSpec.configuration.include RspecApiDocumentation::DSL::Callback, :api_doc_dsl => :callback
+RSpec.configuration.backtrace_exclusion_patterns << %r{lib/rspec_api_documentation/dsl\.rb}

data/lib/rspec_api_documentation/dsl/callback.rb

@@ -0,0 +1,25 @@
+module RspecApiDocumentation::DSL
+  module Callback
+    extend ActiveSupport::Concern
+
+    delegate :request_method, :request_headers, :request_body, :to => :destination
+
+    module ClassMethods
+      def trigger_callback(&block)
+        define_method(:do_callback) do
+          require 'rack'
+          stub_request(:any, callback_url).to_rack(destination)
+          instance_eval &block
+        end
+      end
+    end
+
+    def destination
+      @destination ||= RspecApiDocumentation::TestServer.new(self)
+    end
+
+    def callback_url
+      raise "You must define callback_url"
+    end
+  end
+end

data/lib/rspec_api_documentation/dsl/endpoint.rb

@@ -0,0 +1,134 @@
+require 'rspec/core/formatters/base_formatter'
+require 'rack/utils'
+require 'rack/test/utils'
+
+module RspecApiDocumentation::DSL
+  module Endpoint
+    extend ActiveSupport::Concern
+    include Rack::Test::Utils
+
+    delegate :response_headers, :status, :response_status, :response_body, :to => :rspec_api_documentation_client
+
+    module ClassMethods
+      def example_request(description, params = {}, &block)
+        file_path = caller.first[0, caller.first =~ /:/]
+
+        location = caller.first[0, caller.first =~ /(:in|$)/]
+        location = relative_path(location)
+
+        example description, :location => location, :file_path => file_path do
+          do_request(params)
+          instance_eval &block if block_given?
+        end
+      end
+
+      private
+      # from rspec-core
+      def relative_path(line)
+        line = line.sub(File.expand_path("."), ".")
+        line = line.sub(/\A([^:]+:\d+)$/, '\\1')
+        return nil if line == '-e:1'
+        line
+      end
+    end
+
+    def do_request(extra_params = {})
+      @extra_params = extra_params
+
+      params_or_body = nil
+      path_or_query = path
+
+      if method == :get && !query_string.blank?
+        path_or_query += "?#{query_string}"
+      else
+        params_or_body = respond_to?(:raw_post) ? raw_post : params
+      end
+
+      rspec_api_documentation_client.send(method, path_or_query, params_or_body, headers)
+    end
+
+    def query_string
+      build_nested_query(params || {})
+    end
+
+    def params
+      parameters = example.metadata.fetch(:parameters, {}).inject({}) do |hash, param|
+        set_param(hash, param)
+      end
+      parameters.merge!(extra_params)
+      parameters
+    end
+
+    def headers
+      return unless example.metadata[:headers]
+      example.metadata[:headers].inject({}) do |hash, (header, value)|
+        if value.is_a?(Symbol)
+          hash[header] = send(value) if respond_to?(value)
+        else
+          hash[header] = value
+        end
+        hash
+      end
+    end
+
+    def method
+      example.metadata[:method]
+    end
+
+    def in_path?(param)
+      path_params.include?(param)
+    end
+
+    def path_params
+      example.metadata[:route].scan(/:(\w+)/).flatten
+    end
+
+    def path
+      example.metadata[:route].gsub(/:(\w+)/) do |match|
+        if extra_params.keys.include?($1)
+          delete_extra_param($1)
+        elsif respond_to?($1)
+          send($1)
+        else
+          match
+        end
+      end
+    end
+
+    def explanation(text)
+      example.metadata[:explanation] = text
+    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)|
+        h[k.to_s] = v
+        h
+      end
+    end
+
+    def delete_extra_param(key)
+      @extra_params.delete(key.to_sym) || @extra_params.delete(key.to_s)
+    end
+
+    def set_param(hash, param)
+      key = param[:name]
+      return hash if !respond_to?(key) || in_path?(key)
+
+      if param[:scope]
+        hash[param[:scope].to_s] ||= {}
+        hash[param[:scope].to_s][key] = send(key)
+      else
+        hash[key] = send(key)
+      end
+
+      hash
+    end
+  end
+end