dox 1.1.0 → 2.0.0

data/Rakefile

@@ -1,6 +1,6 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "dox"
+require 'bundler/setup'
+require 'dox'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +10,5 @@ require "dox"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start

data/dox.gemspec

@@ -1,5 +1,4 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'dox/version'
 
@@ -9,31 +8,33 @@ Gem::Specification.new do |spec|
   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.summary       = 'Generates API documentation for rspec in OpenAPI format.'
   spec.homepage      = 'https://github.com/infinum/dox'
   spec.license       = 'MIT'
 
-  spec.required_ruby_version = '>=2.0.0'
+  spec.required_ruby_version = '>= 2.0.0'
 
   # 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'
-  else
-    raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.'
-  end
+  raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.' unless spec.respond_to?(:metadata)
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.11'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'codeclimate-test-reporter'
+  spec.add_development_dependency 'json'
+  spec.add_development_dependency 'pry-nav'
+  spec.add_development_dependency 'pry-rails'
+  spec.add_development_dependency 'pry-stack_explorer'
+  spec.add_runtime_dependency 'rails', '>= 4.0'
+  spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'rubocop'
   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/lib/dox.rb

@@ -19,10 +19,16 @@ require 'dox/errors/invalid_action_error'
 require 'dox/errors/invalid_resource_error'
 require 'dox/errors/invalid_resource_group_error'
 require 'dox/formatter'
+require 'dox/formatters/base'
+require 'dox/formatters/json'
+require 'dox/formatters/multipart'
+require 'dox/formatters/plain'
+require 'dox/formatters/xml'
 require 'dox/printers/base_printer'
 require 'dox/printers/action_printer'
 require 'dox/printers/document_printer'
-require 'dox/printers/example_printer'
+require 'dox/printers/example_request_printer'
+require 'dox/printers/example_response_printer'
 require 'dox/printers/resource_group_printer'
 require 'dox/printers/resource_printer'
 require 'dox/util/http'
@@ -43,4 +49,11 @@ module Dox
   def self.full_headers_whitelist
     (config.headers_whitelist.to_a + DEFAULT_HEADERS_WHITELIST).uniq
   end
+
+  RSpec.configure do |config|
+    config.after(:each, :dox) do |example|
+      example.metadata[:request] = request
+      example.metadata[:response] = response
+    end
+  end
 end

data/lib/dox/config.rb

@@ -1,16 +1,50 @@
 module Dox
   class Config
-    attr_reader :header_file_path, :desc_folder_path
+    attr_reader :schema_request_folder_path
+    attr_reader :schema_response_folder_path
+    attr_reader :schema_response_fail_file_path
     attr_accessor :headers_whitelist
+    attr_accessor :openapi_version
+    attr_accessor :api_version
+    attr_accessor :title
+    attr_accessor :header_description
+    attr_accessor :groups_order
+    attr_reader :descriptions_location
 
-    def header_file_path=(file_path)
+    def descriptions_location=(folder_path)
+      raise(Errors::FolderNotFoundError, folder_path) unless Dir.exist?(folder_path)
+
+      @descriptions_location = folder_path
+    end
+
+    def schema_request_folder_path=(folder_path)
+      raise(Errors::FolderNotFoundError, folder_path) unless Dir.exist?(folder_path)
+
+      @schema_request_folder_path = folder_path
+    end
+
+    def schema_response_folder_path=(folder_path)
+      raise(Errors::FolderNotFoundError, folder_path) unless Dir.exist?(folder_path)
+
+      @schema_response_folder_path = folder_path
+    end
+
+    def schema_response_fail_file_path=(file_path)
       raise(Errors::FileNotFoundError, file_path) unless File.exist?(file_path)
-      @header_file_path = file_path
+
+      @schema_response_fail_file_path = file_path
     end
 
     def desc_folder_path=(folder_path)
-      raise(Errors::FolderNotFoundError, folder_path) unless Dir.exist?(folder_path)
-      @desc_folder_path = folder_path
+      warn(
+        'DEPRECATION WARNING: desc_folder_path will be removed in the next release, please use descriptions_location instead' # rubocop:disable Layout/LineLength
+      )
+
+      self.descriptions_location = folder_path
+    end
+
+    def header_file_path=(_file_path)
+      warn('WARNING: header_file_path is no longer used. Move header description to config.header_description.')
     end
   end
 end

data/lib/dox/dsl/action.rb

@@ -8,6 +8,10 @@ module Dox
       attr_writer :path
       attr_writer :desc
       attr_writer :params
+      attr_writer :query_params
+      attr_writer :request_schema
+      attr_writer :response_schema_success
+      attr_writer :response_schema_fail
 
       def initialize(name, &block)
         self.name = name
@@ -17,13 +21,15 @@ module Dox
       end
 
       def config
-        {
+        { action_request_schema: @request_schema.presence,
+          action_response_schema_success: @response_schema_success.presence,
+          action_response_schema_fail: @response_schema_fail.presence,
           action_name: @name.presence,
           action_verb: @verb.presence,
           action_path: @path.presence,
-          action_desc: @desc.presence,
-          action_params: @params.presence
-        }
+          action_desc: @desc.presence || '',
+          action_params: @params,
+          action_query_params: @query_params.presence || [] }
       end
     end
   end

data/lib/dox/dsl/documentation.rb

@@ -14,6 +14,8 @@ module Dox
         self._resource = Resource.new(name, &block)
       end
 
+      alias tag resource
+
       def action(name, &block)
         self._action = Action.new(name, &block)
       end
@@ -22,6 +24,8 @@ module Dox
         self._group = ResourceGroup.new(name, &block)
       end
 
+      alias x_tag group
+
       def config
         {}.merge(_resource ? _resource.config : {})
           .merge(_action ? _action.config : {})

data/lib/dox/dsl/resource.rb

@@ -16,7 +16,6 @@ module Dox
 
         raise(Dox::Errors::InvalidResourceError, 'Resource name is required!') if @name.blank?
         raise(Dox::Errors::InvalidResourceError, 'Resource group is required!') if @group.blank?
-        raise(Dox::Errors::InvalidResourceError, 'Resource endpoint is required!') if @endpoint.blank?
       end
 
       def config
@@ -24,7 +23,6 @@ module Dox
           resource_name: @name.presence,
           resource_desc: @desc.presence,
           resource_group_name: @group.presence,
-          resource_endpoint: @endpoint.presence,
           apidoc: true
         }
       end

data/lib/dox/dsl/syntax.rb

@@ -10,6 +10,7 @@ module Dox
 
       def const_missing(name)
         documentation = _subjects[infer_subject(name)]
+
         return super unless documentation
 
         Module.new do

data/lib/dox/entities/action.rb

@@ -1,16 +1,17 @@
 module Dox
   module Entities
     class Action
-      attr_reader :name, :desc, :verb, :path, :uri_params
+      attr_reader :name, :desc, :verb, :path, :resource, :params
       attr_accessor :examples
 
-      def initialize(name, details, request)
+      def initialize(details, request)
         @request = request
-        @name = name
+        @name = details[:action_name]
+        @resource = details[:resource_name]
         @desc = details[:action_desc]
         @verb = details[:action_verb] || request.method
         @path = details[:action_path] || template_path
-        @uri_params = details[:action_params] || template_path_params
+        @params = template_params(details[:action_params], details[:action_query_params] || [])
         @examples = []
 
         validate!
@@ -22,25 +23,44 @@ module Dox
 
       # /pokemons/1 => pokemons/{id}
       def template_path
-        path = request.path.dup.presence || request.fullpath.split("?").first
+        path = request.path.dup.presence || request.fullpath.split('?').first
         path_params.each do |key, value|
           path.sub!(%r{\/#{value}(\/|$)}, "/{#{key}}\\1")
         end
+
         path
       end
 
+      def template_params(defined_params, query_params)
+        acquire_path_params + acquire_defined_params(defined_params) + query_params
+      end
+
       def path_params
-        @path_params ||=
-          request.path_parameters.symbolize_keys.except(:action, :controller, :format, :subdomain)
+        request.path_parameters.symbolize_keys.except(:action, :controller, :format, :subdomain)
+      end
+
+      def acquire_path_params
+        return [] if path_params.nil?
+
+        path_params.map do |param, value|
+          { name: param,
+            in: :path,
+            schema: { type: guess_param_type(value) },
+            example: value }
+        end
       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 }
+      def acquire_defined_params(defined_params)
+        return [] if defined_params.nil?
+
+        defined_params.map do |key, value|
+          { name: key,
+            in: 'query',
+            required: value[:required],
+            example: value[:value],
+            description: value[:description].presence || '',
+            schema: { type: value[:type] } }
         end
-        h
       end
 
       def guess_param_type(param)

data/lib/dox/entities/example.rb

@@ -3,20 +3,29 @@ module Dox
     class Example
       extend Forwardable
 
+      attr_reader :desc, :name, :request_schema, :response_schema_success, :response_schema_fail
+
       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]
+        @name = details[:resource_name].downcase
+        @request_schema = details[:action_request_schema]
+        @response_schema_success = details[:action_response_schema_success]
+        @response_schema_fail = details[:action_response_schema_fail]
         @request = request
         @response = response
       end
 
       def request_body
-        @request_body ||= request.body.read
+        @request_body ||= format_content(request, request_content_type)
+      end
+
+      def response_body
+        @response_body ||= format_content(response, response_content_type)
       end
 
       def request_identifier
@@ -31,6 +40,10 @@ module Dox
         @request_headers ||= filter_headers(request)
       end
 
+      def response_success?
+        response.successful?
+      end
+
       # Rails 4 includes the body params in the request_fullpath
       def request_fullpath
         if request.query_parameters.present?
@@ -42,12 +55,29 @@ module Dox
 
       private
 
+      def format_content(http_env, content_type)
+        formatter(content_type).new(http_env).format
+      end
+
+      def formatter(content_type)
+        case content_type
+        when %r{application\/.*json}
+          Dox::Formatters::Json
+        when /xml/
+          Dox::Formatters::Xml
+        when /multipart/
+          Dox::Formatters::Multipart
+        else
+          Dox::Formatters::Plain
+        end
+      end
+
       # Rails 5.0.2 returns "" for request.path
       def request_path
         request.path.presence || request.fullpath.split('?')[0]
       end
 
-      attr_reader :desc, :request, :response
+      attr_reader :request, :response
 
       def filter_headers(obj)
         headers_whitelist.map do |header|

data/lib/dox/entities/resource.rb

@@ -1,17 +1,15 @@
 module Dox
   module Entities
     class Resource
-
-      attr_reader :name, :desc, :endpoint
+      attr_reader :name, :desc, :group
       attr_accessor :actions
 
-      def initialize(name, details)
-        @name = name
+      def initialize(details)
+        @name = details[:resource_name]
+        @group = details[:resource_group_name]
         @desc = details[:resource_desc]
-        @endpoint = details[:resource_endpoint]
         @actions = {}
       end
-
     end
   end
 end

data/lib/dox/entities/resource_group.rb

@@ -1,12 +1,11 @@
 module Dox
   module Entities
     class ResourceGroup
-
       attr_reader :name
       attr_accessor :desc, :resources
 
-      def initialize(name, details)
-        @name = name
+      def initialize(details)
+        @name = details[:resource_group_name]
         @desc = details[:resource_group_desc]
         @resources = {}
       end

data/lib/dox/formatter.rb

@@ -20,7 +20,7 @@ module Dox
 
     def stop(notification)
       if notification.failed_examples.any?
-        $stderr.puts(notification.fully_formatted_failed_examples)
+        warn(notification.fully_formatted_failed_examples)
       else
         printer.print(passed_examples)
       end
@@ -28,7 +28,8 @@ module Dox
 
     def dump_summary(summary)
       return if summary.failed_examples.none?
-      $stderr.puts(summary.fully_formatted)
+
+      warn(summary.fully_formatted)
       exit(-1)
     end
 
@@ -44,28 +45,26 @@ module Dox
       if group
         group.tap { |g| g.desc ||= current_example.resource_group_desc }
       else
-        passed_examples[group_name] = Entities::ResourceGroup.new(group_name,
-                                                                  current_example.metadata)
+        passed_examples[group_name] = Entities::ResourceGroup.new(current_example.metadata)
       end
     end
 
     def load_or_save_resource_to_group(group)
-      resource_name = current_example.resource_name
-      group.resources[resource_name] ||= Entities::Resource.new(resource_name,
-                                                                current_example.metadata)
+      group.resources[current_example.resource_name] ||= Entities::Resource.new(current_example.metadata)
     end
 
     def load_or_save_action_to_resource(resource)
-      action_name = current_example.action_name
-      resource.actions[action_name] ||= Entities::Action.new(action_name, current_example.metadata,
-                                                             current_example.request)
+      resource.actions[current_example.action_name] ||= Entities::Action.new(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.metadata, current_example.request, current_example.response)
+      action.examples << Entities::Example.new(current_example.metadata,
+                                               current_example.request,
+                                               current_example.response)
     end
 
     def printer