rspec-api-documentation 1.1.1.alpha

data/lib/rspec_api_documentation/dsl/resource.rb

@@ -0,0 +1,83 @@
+module RspecApiDocumentation::DSL
+  module Resource
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def self.define_action(method)
+        define_method method do |*args, &block|
+          options = if args.last.is_a?(Hash) then args.pop else {} end
+          options[:method] = method
+          options[:route] = args.first
+          options[:api_doc_dsl] = :endpoint
+          args.push(options)
+          args[0] = "#{method.to_s.upcase} #{args[0]}"
+          context(*args, &block)
+        end
+      end
+
+      define_action :get
+      define_action :post
+      define_action :put
+      define_action :delete
+      define_action :head
+      define_action :patch
+
+      def callback(*args, &block)
+        require 'webmock'
+        self.send(:include, WebMock::API)
+
+        options = if args.last.is_a?(Hash) then args.pop else {} end
+        options[:api_doc_dsl] = :callback
+        args.push(options)
+
+        context(*args, &block)
+      end
+
+      def parameter(name, description, options = {})
+        parameters.push(options.merge(:name => name.to_s, :description => description))
+      end
+
+      def header(name, value)
+        headers[name] = value
+      end
+
+      private
+      def parameters
+        metadata[:parameters] ||= []
+        if superclass_metadata && metadata[:parameters].equal?(superclass_metadata[:parameters])
+          metadata[:parameters] = Marshal.load(Marshal.dump(superclass_metadata[:parameters]))
+        end
+        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
+    end
+
+    def app
+      RspecApiDocumentation.configuration.app
+    end
+
+    def client
+      @client ||= RspecApiDocumentation::RackTestClient.new(self)
+    end
+
+    def no_doc(&block)
+      requests = example.metadata[:requests]
+      example.metadata[:requests] = []
+
+      instance_eval &block
+
+      example.metadata[:requests] = requests
+    end
+  end
+end

data/lib/rspec_api_documentation/example.rb

@@ -0,0 +1,49 @@
+module RspecApiDocumentation
+  class Example
+    attr_reader :example, :configuration
+
+    def initialize(example, configuration)
+      @example = example
+      @configuration = configuration
+    end
+
+    def method_missing(method_sym, *args, &block)
+      if example.metadata.has_key?(method_sym)
+        example.metadata[method_sym]
+      else
+        example.send(method_sym, *args, &block)
+      end
+    end
+
+    def respond_to?(method_sym, include_private = false)
+      super || example.metadata.has_key?(method_sym) || example.respond_to?(method_sym, include_private)
+    end
+
+    def http_method
+      metadata[:method].to_s.upcase
+    end
+
+    def should_document?
+      return false if pending? || !metadata[:resource_name] || !metadata[:document]
+      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?
+      metadata[:public]
+    end
+
+    def has_parameters?
+      respond_to?(:parameters) && parameters.present?
+    end
+
+    def explanation
+      metadata[:explanation] || nil
+    end
+
+    def requests
+      metadata[:requests] || []
+    end
+  end
+end

data/lib/rspec_api_documentation/headers.rb

@@ -0,0 +1,32 @@
+module RspecApiDocumentation
+  module Headers
+    private
+
+    def env_to_headers(env)
+      headers = {}
+      env.each do |key, value|
+        # HTTP_ACCEPT_CHARSET => Accept-Charset
+        if key =~ /^(HTTP_|CONTENT_TYPE)/
+          header = key.gsub(/^HTTP_/, '').titleize.split.join("-")
+          headers[header] = value
+        end
+      end
+      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}"
+      end.join("\n")
+    end
+  end
+end

data/lib/rspec_api_documentation/index.rb

@@ -0,0 +1,7 @@
+module RspecApiDocumentation
+  class Index
+    def examples
+      @examples ||= []
+    end
+  end
+end

data/lib/rspec_api_documentation/oauth2_mac_client.rb

@@ -0,0 +1,70 @@
+begin
+  require "active_support/secure_random"
+rescue LoadError
+  # ActiveSupport::SecureRandom not provided in activesupport >= 3.2
+end
+require "webmock"
+require "rack/oauth2"
+
+module RspecApiDocumentation
+  class OAuth2MACClient < ClientBase
+    include WebMock::API
+    attr_accessor :last_response, :last_request
+    private :last_response, :last_request
+
+    def request_headers
+      env_to_headers(last_request.env)
+    end
+
+    def response_headers
+      last_response.headers
+    end
+
+    def query_string
+      last_request.env["QUERY_STRING"]
+    end
+
+    def status
+      last_response.status
+    end
+
+    def response_body
+      last_response.body
+    end
+
+    def request_content_type
+      last_request.content_type
+    end
+
+    def response_content_type
+      last_response.content_type
+    end
+
+    protected
+
+    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)
+      def call(env)
+        env["QUERY_STRING"] = query_string_hack(env)
+        client.last_request = Struct.new(:env, :content_type).new(env, env["CONTENT_TYPE"])
+        app.call(env.merge("SCRIPT_NAME" => ""))
+      end
+
+    private
+      def query_string_hack(env)
+        env["QUERY_STRING"].gsub('%5B', '[').gsub('%5D', ']').gsub(/\[\d+/) { |s| "#{$1}[" }
+      end
+    end
+
+    def access_token
+      @access_token ||= begin
+                          app = ProxyApp.new(self, context.app)
+                          stub_request(:any, %r{http://example\.com}).to_rack(app)
+                          Rack::OAuth2::Client.new(options.merge(:host => "example.com", :scheme => "http")).access_token!
+                        end
+    end
+  end
+end

data/lib/rspec_api_documentation/rack_test_client.rb

@@ -0,0 +1,58 @@
+module RspecApiDocumentation
+  class RackTestClient < ClientBase
+
+    delegate :last_request, :last_response, :to => :rack_test_session
+    private :last_request, :last_response
+
+    def request_headers
+      env_to_headers(last_request.env)
+    end
+
+    def response_headers
+      last_response.headers
+    end
+
+    def query_string
+      last_request.env["QUERY_STRING"]
+    end
+
+    def status
+      last_response.status
+    end
+
+    def response_body
+      last_response.body
+    end
+
+    def request_content_type
+      last_request.content_type
+    end
+
+    def response_content_type
+      last_response.content_type
+    end
+
+    protected
+
+    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
+
+    def rack_test_session
+      @rack_test_session ||= Struct.new(:app) do
+        begin
+          require "rack/test"
+          include Rack::Test::Methods
+        rescue LoadError
+          raise "#{self.class.name} requires Rack::Test >= 0.5.5. Please add it to your test dependencies."
+        end
+      end.new(app)
+    end
+  end
+end

data/lib/rspec_api_documentation/railtie.rb

@@ -0,0 +1,7 @@
+module RspecApiDocumentation
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load "tasks/docs.rake"
+    end
+  end
+end

data/lib/rspec_api_documentation/test_server.rb

@@ -0,0 +1,31 @@
+module RspecApiDocumentation
+  class TestServer < Struct.new(:context)
+    include Headers
+
+    delegate :example, :to => :context
+    delegate :metadata, :to => :example
+
+    attr_reader :request_method, :request_headers, :request_body
+
+    def call(env)
+      input = env["rack.input"]
+      input.rewind
+
+      @request_method = env["REQUEST_METHOD"]
+      @request_headers = env_to_headers(env)
+      @request_body = input.read
+
+      request_metadata = {}
+
+      request_metadata[:request_method] = @request_method
+      request_metadata[:request_path] = env["PATH_INFO"]
+      request_metadata[:request_body] = @request_body
+      request_metadata[:request_headers] = @request_headers
+
+      metadata[:requests] ||= []
+      metadata[:requests] << request_metadata
+
+      return [200, {}, [""]]
+    end
+  end
+end

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