dox 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f6271f722c9d2fe3887a8e0732ceff6228f4f9c9
-  data.tar.gz: 8d44754eeefedee5c76d5f87ab529bb80a2ec0ab
+  metadata.gz: 1ff74ac34c68966c8eeb8ae9de609bd4eca79e4d
+  data.tar.gz: 4df71ab4f1315a7e1947fd94c2e4ff156a3fab25
 SHA512:
-  metadata.gz: caa994fabaa650442c1e8e669ee99bc9b32ab16b06b7387e3b2bf128bed393cb5bffb8099b20d2db71b93cfef2abac2807ba9f037ed85e654eac33187ef2a98e
-  data.tar.gz: b430db71dbfbadf6579c11da1d8a904c6914dd54b694cc24156e46f970228860fd0d33bee37aca42826bca1293687632be2c39b458bf7144a1b7abc331d83bc1
+  metadata.gz: 6140c2ebe30c6bb2cf621a480dfb1bf06c3caac0c4b337ba74089ae804c0cd5bfc80d3651c51d552cd020169bb50e5ef72ab77094341b8d13f293112edaeb14d
+  data.tar.gz: da8ec16081224370f2afed78fe15963a9c2f8bd6f45189faf966f8770fb02b33924bd7792a093a7dd0c148484175697e6e1cc4eed9fce0fd769a63170aea762a

data/CHANGES.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Version 1.2.0
+
+Released on November 27, 2019
+
+New:
+- Support Multipart payload with pretty formatting (based on `content-type` header)
+
+Fix:
+- Explicit passing of an empty hash for `params` in actions now works as expected
+
+
 ## Version 1.1.0
 
 Released on February 19, 2018

data/README.md

@@ -4,7 +4,7 @@
 
 # Dox
 
-Automate your documentation writing proces! Dox generates API documentation from Rspec controller/request specs in a Rails application. It formats the tests output in the [API Blueprint](https://apiblueprint.org) format. Choose one of the [renderes](#renderers) to convert it to HTML or host it on [Apiary.io](https://apiary.io)
+Automate your documentation writing process! Dox generates API documentation from Rspec controller/request specs in a Rails application. It formats the test's output in the [API Blueprint](https://apiblueprint.org) format. Choose one of the [renderers](#renderers) to convert it to HTML or host it on [Apiary.io](https://apiary.io)
 
 Here's a [demo app](https://github.com/infinum/dox-demo) and here are some examples:
 
@@ -297,6 +297,16 @@ Or you can just take your generated markdown and host your documentation on [Api
 
 You might experience some strange issues when generating the documentation. Here are a few examples of what we've encountered so far.
 
+#### Uninitialized constant errors
+
+There seems to be a problem with **rspec-rails** versions 3.7 and later not automatically requiring the project's rails_helper.rb when run with the `--format` flag.
+
+To fix this issue, generate your documentation with `--require rails_helper`:
+
+```
+bundle exec rspec -f Dox::Formatter --order defined --tag dox --out docs.md --require rails_helper
+```
+
 #### Wrap parameters issue
 Rails wraps JSON parameters on all requests by default, which results with documented requests looking like this:
 

data/lib/dox.rb

@@ -19,6 +19,11 @@ 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'

data/lib/dox/dsl/action.rb

@@ -22,7 +22,7 @@ module Dox
           action_verb: @verb.presence,
           action_path: @path.presence,
           action_desc: @desc.presence,
-          action_params: @params.presence
+          action_params: @params
         }
       end
     end

data/lib/dox/entities/example.rb

@@ -5,7 +5,6 @@ module Dox
 
       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
 
@@ -16,7 +15,11 @@ module Dox
       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
@@ -42,6 +45,23 @@ 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]

data/lib/dox/formatters/base.rb

@@ -0,0 +1,19 @@
+module Dox
+  module Formatters
+    class Base
+      def initialize(http_env)
+        @http_env = http_env
+        http_env_body = http_env.body
+        @body = http_env_body.respond_to?(:read) ? http_env_body.read : http_env_body
+      end
+
+      def format
+        raise 'no format method defined in formatter'
+      end
+
+      private
+
+      attr_reader :http_env, :body
+    end
+  end
+end

data/lib/dox/formatters/json.rb

@@ -0,0 +1,14 @@
+module Dox
+  module Formatters
+    class Json < Dox::Formatters::Base
+      def format
+        # in cases where the body isn't valid JSON
+        # and the headers specify the Content-Type is application/json
+        # an error should be raised
+        return '' if body.nil? || body.length < 2
+
+        JSON.pretty_generate(JSON.parse(body))
+      end
+    end
+  end
+end

data/lib/dox/formatters/multipart.rb

@@ -0,0 +1,21 @@
+module Dox
+  module Formatters
+    class Multipart
+      def initialize(http_env)
+        @http_env = http_env
+      end
+
+      def format
+        JSON.pretty_generate(extracted_multipart)
+      end
+
+      private
+
+      def extracted_multipart
+        Rack::Multipart.extract_multipart(http_env)
+      end
+
+      attr_reader :http_env
+    end
+  end
+end

data/lib/dox/formatters/plain.rb

@@ -0,0 +1,9 @@
+module Dox
+  module Formatters
+    class Plain < Dox::Formatters::Base
+      def format
+        body
+      end
+    end
+  end
+end

data/lib/dox/formatters/xml.rb

@@ -0,0 +1,14 @@
+module Dox
+  module Formatters
+    class Xml < Dox::Formatters::Base
+      def format
+        doc = REXML::Document.new(body)
+        formatter = REXML::Formatters::Pretty.new
+        formatter.compact = true
+        result = ''
+        formatter.write(doc, result)
+        result
+      end
+    end
+  end
+end

data/lib/dox/printers/example_printer.rb

@@ -54,7 +54,7 @@ module Dox
 
     + Body
 
-#{indent_lines(12, formatted_body(example.request_body, example.request_content_type))}
+#{indent_lines(12, example.request_body)}
         HEREDOC
       end
 
@@ -79,42 +79,10 @@ module Dox
 
     + Body
 
-#{indent_lines(12, formatted_body(example.response_body, example.response_content_type))}
+#{indent_lines(12, example.response_body)}
         HEREDOC
       end
 
-      def formatted_body(body_str, content_type)
-        case content_type
-        when %r{application\/.*json}
-          pretty_json(safe_json_parse(body_str))
-        when /xml/
-          pretty_xml(body_str)
-        else
-          body_str
-        end
-      end
-
-      def safe_json_parse(json_string)
-        json_string.length >= 2 ? JSON.parse(json_string) : nil
-      end
-
-      def pretty_json(json_string)
-        if json_string.present?
-          JSON.pretty_generate(json_string)
-        else
-          ''
-        end
-      end
-
-      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 print_headers(headers)
         headers.map do |key, value|
           "#{key}: #{value}"

data/lib/dox/version.rb

@@ -1,3 +1,3 @@
 module Dox
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dox
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Melita Kokot
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-19 00:00:00.000000000 Z
+date: 2019-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -166,6 +166,11 @@ files:
 - lib/dox/errors/invalid_resource_error.rb
 - lib/dox/errors/invalid_resource_group_error.rb
 - lib/dox/formatter.rb
+- lib/dox/formatters/base.rb
+- lib/dox/formatters/json.rb
+- lib/dox/formatters/multipart.rb
+- lib/dox/formatters/plain.rb
+- lib/dox/formatters/xml.rb
 - lib/dox/printers/action_printer.rb
 - lib/dox/printers/base_printer.rb
 - lib/dox/printers/document_printer.rb