dox 1.0.0.alpha → 1.0.0

data/dox.gemspec

@@ -4,32 +4,34 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'dox/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "dox"
+  spec.name          = 'dox'
   spec.version       = Dox::VERSION
-  spec.authors       = ["Melita Kokot"]
-  spec.email         = ["melita.kokot@gmail.com"]
+  spec.authors       = ['Melita Kokot', 'Vedran Hrnčić']
+  spec.email         = ['melita.kokot@gmail.com', 'vrabac266@gmail.com']
 
-  spec.summary       = "Generates API documentation for rspec in api blueprint format."
-  spec.homepage      = "https://github.com/infinum/dox"
-  spec.license       = "MIT"
+  spec.summary       = 'Generates API documentation for rspec in api blueprint format.'
+  spec.homepage      = 'https://github.com/infinum/dox'
+  spec.license       = 'MIT'
 
   # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
   # delete this section to allow pushing this gem to any host.
   if spec.respond_to?(:metadata)
-    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+    spec.metadata['allowed_push_host'] = 'https://rubygems.org'
   else
-    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+    raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.'
   end
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency "bundler", "~> 1.11"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "pry"
-  spec.add_runtime_dependency "rspec-core"
-  spec.add_runtime_dependency "rails", ">= 4.0"
+  spec.add_development_dependency 'bundler', '~> 1.11'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'codeclimate-test-reporter'
+  spec.add_runtime_dependency 'rspec-core'
+  spec.add_runtime_dependency 'rails', '>= 4.0'
 end

data/exe/dox

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+puts `bundle exec rspec --tag apidoc -f Dox::Formatter --order defined #{ARGV.to_a.join(' ')}`

data/lib/dox.rb

@@ -1,3 +1,7 @@
+require 'active_support/concern'
+require 'active_support/core_ext/string'
+require 'forwardable'
+
 require 'dox/config'
 require 'dox/dsl/attr_proxy'
 require 'dox/dsl/action'
@@ -21,19 +25,22 @@ require 'dox/printers/document_printer'
 require 'dox/printers/example_printer'
 require 'dox/printers/resource_group_printer'
 require 'dox/printers/resource_printer'
+require 'dox/util/http'
 require 'dox/version'
 
-
 module Dox
-  class << self
-    attr_writer :config
-  end
+  Error = Class.new(StandardError)
 
   def self.configure
     yield(config) if block_given?
   end
 
   def self.config
-    @conifg ||= Dox::Config.new
+    @config ||= Dox::Config.new
+  end
+
+  DEFAULT_HEADERS_WHITELIST = ['Accept', 'Content-Type'].freeze
+  def self.full_headers_whitelist
+    (config.headers_whitelist.to_a + DEFAULT_HEADERS_WHITELIST).uniq
   end
 end

data/lib/dox/config.rb

@@ -1,18 +1,16 @@
 module Dox
   class Config
-
     attr_reader :header_file_path, :desc_folder_path
+    attr_accessor :headers_whitelist
 
     def header_file_path=(file_path)
-      raise(Errors::FileNotFoundError, file_path) unless File.exists?(file_path)
+      raise(Errors::FileNotFoundError, file_path) unless File.exist?(file_path)
       @header_file_path = file_path
     end
 
     def desc_folder_path=(folder_path)
-      raise(Errors::FolderNotFoundError, folder_path) unless Dir.exists?(folder_path)
+      raise(Errors::FolderNotFoundError, folder_path) unless Dir.exist?(folder_path)
       @desc_folder_path = folder_path
     end
-
   end
 end
-

data/lib/dox/dsl/attr_proxy.rb

@@ -2,7 +2,7 @@ module Dox
   module DSL
     module AttrProxy
       def method_missing(name, value)
-        setter = "#{name.to_s}="
+        setter = "#{name}="
         return super unless respond_to? setter
 
         public_send setter, value

data/lib/dox/dsl/documentation.rb

@@ -19,7 +19,7 @@ module Dox
       end
 
       def group(name, &block)
-        self._group = ResourceGroup.new(name: name, &block)
+        self._group = ResourceGroup.new(name, &block)
       end
 
       def config

data/lib/dox/entities/action.rb

@@ -10,23 +10,49 @@ module Dox
         @desc = details[:action_desc]
         @verb = details[:action_verb] || request.method
         @path = details[:action_path] || template_path
-        @uri_params = details[:action_params]
+        @uri_params = details[:action_params] || template_path_params
         @examples = []
+
+        validate!
       end
 
       private
 
       attr_reader :request
 
+      # /pokemons/1 => pokemons/{id}
       def template_path
-        path_params = request.path_parameters.symbolize_keys.except(:action, :controller)
-        path = request.path.dup
+        path = request.path.dup.presence || request.fullpath.split("?").first
         path_params.each do |key, value|
-          # /pokemons/1 => pokemons/{id}
-          path.sub!(/\/#{value}(\/|$)/, "/{#{key}}\\1")
+          path.sub!(%r{\/#{value}(\/|$)}, "/{#{key}}\\1")
         end
         path
       end
+
+      def path_params
+        @path_params ||= request.path_parameters.symbolize_keys.except(:action, :controller, :format)
+      end
+
+      def template_path_params
+        h = {}
+        path_params.each do |param, value|
+          param_type = guess_param_type(value)
+          h[param] = { type: param_type, required: :required, value: value }
+        end
+        h
+      end
+
+      def guess_param_type(param)
+        if param =~ /^\d+$/
+          :number
+        else
+          :string
+        end
+      end
+
+      def validate!
+        raise(Error, "Unrecognized HTTP verb #{verb}") unless Util::Http.verb?(verb)
+      end
     end
   end
 end

data/lib/dox/entities/example.rb

@@ -1,8 +1,13 @@
 module Dox
   module Entities
     class Example
+      extend Forwardable
 
-      attr_reader :desc, :request, :response
+      def_delegator :response, :status, :response_status
+      def_delegator :response, :content_type, :response_content_type
+      def_delegator :response, :body, :response_body
+      def_delegator :request, :content_type, :request_content_type
+      def_delegator :request, :method, :request_method
 
       def initialize(details, request, response)
         @desc = details[:description]
@@ -11,29 +16,57 @@ module Dox
       end
 
       def request_parameters
-        request.parameters.except(*request.path_parameters.keys.map(&:to_s)).except(*request.query_parameters.keys.map(&:to_s))
-      end
-
-      def request_content_type
-        request.content_type
+        request.parameters
+               .except(*request.path_parameters.keys.map(&:to_s))
+               .except(*request.query_parameters.keys.map(&:to_s))
       end
 
       def request_identifier
         @desc
       end
 
-      def response_status
-        response.status
+      def response_headers
+        @response_headers ||= filter_headers(response)
+      end
+
+      def request_headers
+        @request_headers ||= filter_headers(request)
+      end
+
+      # Rails 4 includes the body params in the request_fullpath
+      def request_fullpath
+        if request.query_parameters.present?
+          "#{request_path}?#{request_url_query_parameters}"
+        else
+          request_path
+        end
       end
 
-      def response_content_type
-        response.content_type
+      private
+
+      # Rails 5.0.2 returns "" for request.path
+      def request_path
+        request.path.presence || request.fullpath.split("?")[0]
       end
 
-      def response_body
-        response.body
+      attr_reader :desc, :request, :response
+
+      def filter_headers(obj)
+        headers_whitelist.map do |header|
+          header_val = obj.headers[header]
+          next if header_val.blank?
+
+          [header, header_val]
+        end.compact
       end
 
+      def headers_whitelist
+        @headers_whitelist ||= Dox.full_headers_whitelist
+      end
+
+      def request_url_query_parameters
+        CGI.unescape(request.query_parameters.to_query)
+      end
     end
   end
 end

data/lib/dox/formatter.rb

@@ -1,86 +1,110 @@
+require 'rspec/core'
 require 'rspec/core/formatters/base_formatter'
-require 'pry'
 
 module Dox
   class Formatter < RSpec::Core::Formatters::BaseFormatter
+    extend Forwardable
 
-    RSpec::Core::Formatters.register self, :example_passed, :example_started, :stop
+    RSpec::Core::Formatters.register self, :example_passed, :stop
 
     def initialize(output)
       super
-      @passed_examples = {}
-      @group_level = 0
-    end
-
-    def example_started(notification)
-      @example_group_instance = notification.example.example_group_instance
+      self.passed_examples = {}
     end
 
     def example_passed(passed)
-      @current_example_data = passed.example.metadata
-      if should_document_example?
-        move_example_to_passed
-      end
-      @example_group_instance = nil
+      self.current_example = CurrentExample.new(passed.example)
+      move_example_to_passed if current_example.document?
     end
 
     def stop(_notification)
-      printer.print(@passed_examples)
+      printer.print(passed_examples)
     end
 
     private
 
+    attr_accessor :passed_examples
+    attr_accessor :current_example
+
     def load_or_save_group
-      group_name = @current_example_data[:resource_group_name]
-      group = @passed_examples[group_name]
+      group_name = current_example.resource_group_name
+      group = passed_examples[group_name]
 
       if group
-        group.desc ||= @current_example_data[:resource_group_desc]
-        group
+        group.tap { |g| g.desc ||= current_example.resource_group_desc }
       else
-        @passed_examples[group_name] = Entities::ResourceGroup.new(group_name, @current_example_data)
+        passed_examples[group_name] = Entities::ResourceGroup.new(group_name,
+                                                                  current_example.metadata)
       end
     end
 
     def load_or_save_resource_to_group(group)
-      resource_name = @current_example_data[:resource_name]
-      group.resources[resource_name] ||= Entities::Resource.new(resource_name, @current_example_data)
+      resource_name = current_example.resource_name
+      group.resources[resource_name] ||= Entities::Resource.new(resource_name,
+                                                                current_example.metadata)
     end
 
     def load_or_save_action_to_resource(resource)
-      action_name = @current_example_data[:action_name]
-      resource.actions[action_name] ||= Entities::Action.new(action_name, @current_example_data, request)
+      action_name = current_example.action_name
+      resource.actions[action_name] ||= Entities::Action.new(action_name, current_example.metadata,
+                                                             current_example.request)
     end
 
     def move_example_to_passed
       group = load_or_save_group
       resource = load_or_save_resource_to_group(group)
       action = load_or_save_action_to_resource(resource)
-      action.examples << Entities::Example.new(@current_example_data, request, response)
+      action.examples << Entities::Example.new(current_example.metadata, current_example.request, current_example.response)
     end
 
-    def should_document_example?
-      @current_example_data[:apidoc] &&
-        !@current_example_data[:nodoc]
-      # error check
-      #&&
-        # @current_example_data[:resource_group] &&
-        # @current_example_data[:resource] &&
-        # @current_example_data[:action] &&
-        # !@current_example_data[:nodoc]
+    def printer
+      @printer ||= Printers::DocumentPrinter.new(output)
     end
 
-    def request
-      @example_group_instance.request
-    end
+    class CurrentExample # :nodoc:
+      extend Forwardable
 
-    def response
-      @example_group_instance.response
-    end
+      delegate [:metadata] => :example
 
-    def printer
-      @printer ||= Printers::DocumentPrinter.new(output)
-    end
+      attr_reader :example
+
+      def initialize(example)
+        @example = example
+      end
+
+      def resource_group_name
+        metadata[:resource_group_name]
+      end
 
+      def resource_group_desc
+        metadata[:resource_group_desc]
+      end
+
+      def resource_name
+        metadata[:resource_name]
+      end
+
+      def action_name
+        metadata[:action_name]
+      end
+
+      def request
+        metadata[:request]
+      end
+
+      def response
+        metadata[:response]
+      end
+
+      def document?
+        tagged_with?(:apidoc) && tagged_with?(:dox) && !tagged_with?(:nodoc)
+      end
+
+      private
+
+      def tagged_with?(key)
+        metadata.key?(key) && metadata[key] == true
+      end
+    end
   end
 end

data/lib/dox/printers/action_printer.rb

@@ -1,13 +1,10 @@
 module Dox
   module Printers
     class ActionPrinter < BasePrinter
-
       def print(action)
-        @output.puts "### #{action.name} [#{action.verb} #{action.path}]\n\n#{print_desc(action.desc)}\n\n"
-
-        if action.uri_params.present?
-          @output.puts("+ Parameters\n#{formatted_params(action.uri_params)}")
-        end
+        self.action = action
+        @output.puts action_title
+        @output.puts action_uri_params if action.uri_params.present?
 
         action.examples.each do |example|
           example_printer.print(example)
@@ -16,16 +13,35 @@ module Dox
 
       private
 
+      attr_accessor :action
+
+      def action_title
+        <<-HEREDOC
+
+### #{action.name} [#{action.verb.upcase} #{action.path}]
+#{print_desc(action.desc)}
+        HEREDOC
+      end
+
+      def action_uri_params
+        <<-HEREDOC
++ Parameters
+#{formatted_params(action.uri_params)}
+        HEREDOC
+      end
+
       def example_printer
         @example_printer ||= ExamplePrinter.new(@output)
       end
 
       def formatted_params(uri_params)
         uri_params.map do |param, details|
-          "    + #{CGI.escape(param.to_s)}: `#{CGI.escape(details[:value].to_s)}` (#{details[:type]}, #{details[:required]}) - #{details[:description]}"
+          desc = "    + #{CGI.escape(param.to_s)}: `#{CGI.escape(details[:value].to_s)}` (#{details[:type]}, #{details[:required]})"
+          desc += " - #{details[:description]}" if details[:description].present?
+          desc += "\n        + Default: #{details[:default]}" if details[:default].present?
+          desc
         end.flatten.join("\n")
       end
-
     end
   end
 end