dox 1.3.0 → 2.0.0.beta1

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,6 +3,8 @@ 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 :request, :content_type, :request_content_type
@@ -10,6 +12,10 @@ module Dox
 
       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
@@ -34,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?
@@ -67,7 +77,7 @@ module Dox
         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,16 @@
 module Dox
   module Entities
     class Resource
-
-      attr_reader :name, :desc, :endpoint
+      attr_reader :name, :desc, :endpoint, :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

data/lib/dox/printers/action_printer.rb

@@ -3,44 +3,35 @@ module Dox
     class ActionPrinter < BasePrinter
       def print(action)
         self.action = action
-        @output.puts action_title
-        @output.puts action_uri_params if action.uri_params.present?
+        @action_hash = find_or_add(find_or_add(spec, action.path.to_s), action.verb.downcase.to_sym)
 
-        action.examples.each do |example|
-          example_printer.print(example)
-        end
+        add_action
+        add_action_params
+
+        print_examples
       end
 
       private
 
-      attr_accessor :action
-
-      def action_title
-        <<-HEREDOC
+      attr_accessor :action, :action_hash
 
-### #{action.name} [#{action.verb.upcase} #{action.path}]
-#{print_desc(action.desc)}
-        HEREDOC
+      def add_action
+        action_hash['summary'] = action.name
+        action_hash['tags'] = [action.resource]
+        action_hash['description'] = format_desc(action.desc)
       end
 
-      def action_uri_params
-        <<-HEREDOC
-+ Parameters
-#{formatted_params(action.uri_params)}
-        HEREDOC
-      end
+      def add_action_params
+        return unless action.params.present?
 
-      def example_printer
-        @example_printer ||= ExamplePrinter.new(@output)
+        action_hash['parameters'] = action.params
       end
 
-      def formatted_params(uri_params)
-        uri_params.map do |param, details|
-          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")
+      def print_examples
+        action.examples.each do |example|
+          ExampleRequestPrinter.new(action_hash).print(example)
+          ExampleResponsePrinter.new(action_hash).print(example)
+        end
       end
     end
   end

data/lib/dox/printers/base_printer.rb

@@ -1,37 +1,56 @@
+require 'rexml/document'
+
 module Dox
   module Printers
     class BasePrinter
-      def initialize(output)
-        @output = output
+      attr_reader :spec
+
+      def initialize(spec)
+        @spec = spec || {}
       end
 
       def print
         raise NotImplementedError
       end
 
-      private
+      def find_or_add(hash, key, default = {})
+        return hash[key] if hash.key?(key)
 
-      def descriptions_folder_path
-        Dox.config.desc_folder_path
+        hash[key] = default
       end
 
-      def print_desc(desc, fullpath = false)
-        return if desc.blank?
+      def read_file(path, root_path: Dox.config.descriptions_location)
+        return '' unless root_path
+
+        File.read(File.join(root_path, path))
+      end
 
-        if desc.to_s =~ /.*\.md$/
-          path = if fullpath
-                   desc
-                 else
-                   descriptions_folder_path.join(desc).to_s
-                 end
-          content(path)
+      def formatted_body(body_str, content_type)
+        case content_type
+        when %r{application\/.*json}
+          JSON.parse(body_str)
+        when /xml/
+          pretty_xml(body_str)
         else
-          desc
+          body_str
         end
       end
 
-      def content(path)
-        File.read(path)
+      def pretty_xml(xml_string)
+        doc = REXML::Document.new(xml_string)
+        formatter = REXML::Formatters::Pretty.new
+        formatter.compact = true
+        result = ''
+        formatter.write(doc, result)
+        result
+      end
+
+      def format_desc(description)
+        desc = description
+        desc = '' if desc.nil?
+        desc = read_file(desc) if desc.end_with?('.md')
+
+        desc
       end
     end
   end

data/lib/dox/printers/document_printer.rb

@@ -1,26 +1,46 @@
 module Dox
   module Printers
     class DocumentPrinter < BasePrinter
+      def initialize(output)
+        super(body)
+        @output = output
+      end
+
       def print(passed_examples)
-        print_meta_info
+        spec['paths'] = {}
+        spec['tags'] = []
+        spec['x-tagGroups'] = []
 
         passed_examples.sort.each do |_, resource_group|
           group_printer.print(resource_group)
         end
+
+        @output.puts(JSON.pretty_generate(spec))
       end
 
       private
 
-      def group_printer
-        @group_printer ||= ResourceGroupPrinter.new(@output)
+      def body
+        {
+          openapi: Dox.config.openapi_version || '3.0.0',
+          info: {
+            title: Dox.config.title || 'API Documentation',
+            description: adjust_description(Dox.config.description || ''),
+            version: Dox.config.api_version || '1.0'
+          }
+        }
       end
 
-      def print_meta_info
-        @output.puts(print_desc(api_desc_path))
+      def adjust_description(description)
+        description.end_with?('.md') ? acquire_desc(description) : description
       end
 
-      def api_desc_path
-        Dox.config.header_file_path
+      def acquire_desc(path)
+        read_file(path)
+      end
+
+      def group_printer
+        @group_printer ||= ResourceGroupPrinter.new(spec)
       end
     end
   end

data/lib/dox/printers/example_request_printer.rb

@@ -0,0 +1,69 @@
+module Dox
+  module Printers
+    class ExampleRequestPrinter < BasePrinter
+      def print(example)
+        self.example = example
+        add_example_request
+      end
+
+      private
+
+      attr_accessor :example
+
+      def add_example_request
+        spec['parameters'] = add_new_header_params(find_or_add(spec, 'parameters', []))
+        return if example.request_body.empty?
+
+        add_content(find_or_add(spec, 'requestBody'))
+      end
+
+      def add_content(body)
+        add_content_name(body['content'] = find_or_add(body, 'content'))
+      end
+
+      def add_content_name(body)
+        req_header = find_headers(example.request_headers)
+        add_example(body[req_header] = find_or_add(body, req_header))
+        add_schema(body[req_header], Dox.config.schema_request_folder_path)
+      end
+
+      def add_example(body)
+        add_desc(body['examples'] = find_or_add(body, 'examples'))
+      end
+
+      def add_desc(body)
+        body[example.desc] = { 'summary' => example.desc,
+                               'value' => formatted_body(example.request_body,
+                                                         example.request_content_type) }
+      end
+
+      def add_schema(body, path)
+        return if example.request_schema.nil?
+        return unless path
+
+        file_path = File.join(path, "#{example.request_schema}.json")
+
+        body['schema'] = File.file?(file_path) ? { '$ref' => file_path } : JSON.parse(example.request_schema)
+      end
+
+      def find_headers(headers)
+        headers.find { |key, _| key == 'Accept' }&.last || 'any'
+      end
+
+      def acquire_header_params
+        example.request_headers.map do |key, value|
+          { name: key, in: :header, example: value }
+        end
+      end
+
+      def add_new_header_params(header_params)
+        example.request_headers.each do |key, value|
+          header_params.push(name: key, in: :header, example: value) unless
+            header_params.detect { |hash| hash[:name] == key }
+        end
+
+        header_params
+      end
+    end
+  end
+end

data/lib/dox/printers/example_response_printer.rb

@@ -0,0 +1,86 @@
+module Dox
+  module Printers
+    class ExampleResponsePrinter < BasePrinter
+      def print(example)
+        self.example = example
+        add_example_response
+      end
+
+      private
+
+      attr_accessor :example
+
+      def add_example_response
+        add_statuses(find_or_add(find_or_add(spec, 'responses'), example.response_status.to_s))
+      end
+
+      def add_statuses(body)
+        add_status_desc(body)
+        add_content(body)
+        add_headers(body)
+      end
+
+      def add_status_desc(body)
+        body['description'] = Util::Http::HTTP_STATUS_CODES[example.response_status]
+      end
+
+      def add_content(body)
+        add_content_name(body['content'] = find_or_add(body, 'content'))
+      end
+
+      def add_content_name(body)
+        resp_header = find_headers(example.response_headers)
+
+        add_example(body[resp_header] = find_or_add(body, resp_header))
+        add_schema(body[resp_header], Dox.config.schema_response_folder_path)
+      end
+
+      def add_example(body)
+        return if example.response_body.empty?
+
+        add_desc(body['examples'] = find_or_add(body, 'examples'))
+      end
+
+      def add_desc(body)
+        body[example.desc] = { 'summary' => example.desc,
+                               'value' => formatted_body(example.response_body,
+                                                         find_headers(example.response_headers)) }
+      end
+
+      def add_schema(body, path)
+        return unless path
+
+        schema = find_schema
+
+        return unless schema
+
+        add_schema_to_hash(body, path, schema)
+      end
+
+      def find_schema
+        if example.response_success?
+          example.response_schema_success
+        else
+          example.response_schema_fail || Dox.config.schema_response_fail_file_path
+        end
+      end
+
+      def add_schema_to_hash(body, path, schema)
+        body['schema'] =
+          if schema.is_a?(Pathname)
+            { '$ref' => schema }
+          else
+            { '$ref' => File.join(path, "#{schema}.json") }
+          end
+      end
+
+      def find_headers(headers)
+        headers.find { |key, _| key == 'Content-Type' }&.last || 'any'
+      end
+
+      def add_headers(body)
+        body['headers'] = Hash[example.response_headers.map { |key, value| [key, { description: value }] }]
+      end
+    end
+  end
+end

data/lib/dox/printers/resource_group_printer.rb

@@ -3,7 +3,7 @@ module Dox
     class ResourceGroupPrinter < BasePrinter
       def print(resource_group)
         self.resource_group = resource_group
-        @output.puts resource_group_title
+        add_resource_group
 
         resource_group.resources.each do |_, resource|
           resource_printer.print(resource)
@@ -14,16 +14,16 @@ module Dox
 
       attr_accessor :resource_group
 
-      def resource_group_title
-        <<-HEREDOC
+      def add_resource_group
+        spec['x-tagGroups'].push(name: resource_group.name, 'tags' => []) unless group_included?
+      end
 
-# Group #{resource_group.name}
-#{print_desc(resource_group.desc)}
-        HEREDOC
+      def group_included?
+        spec['x-tagGroups'].find { |group| group[:name] == resource_group.name }
       end
 
       def resource_printer
-        @resource_printer ||= ResourcePrinter.new(@output)
+        @resource_printer ||= ResourcePrinter.new(spec)
       end
     end
   end

data/lib/dox/printers/resource_printer.rb

@@ -3,7 +3,7 @@ module Dox
     class ResourcePrinter < BasePrinter
       def print(resource)
         self.resource = resource
-        @output.puts resource_title
+        add_resources
 
         resource.actions.each do |_, action|
           action_printer.print(action)
@@ -14,16 +14,21 @@ module Dox
 
       attr_accessor :resource
 
-      def resource_title
-        <<-HEREDOC
+      def add_resources
+        add_to_tags
+        add_to_groups
+      end
+
+      def add_to_tags
+        spec['tags'] = spec['tags'].push(name: resource.name, description: format_desc(resource.desc)).uniq
+      end
 
-## #{resource.name} [#{resource.endpoint}]
-#{print_desc(resource.desc)}
-        HEREDOC
+      def add_to_groups
+        spec['x-tagGroups'].find { |group| group[:name] == resource.group }['tags'].push(resource.name)
       end
 
       def action_printer
-        @action_printer ||= ActionPrinter.new(@output)
+        @action_printer ||= ActionPrinter.new(spec['paths'])
       end
     end
   end