dox 1.0.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e3696fee9fddea2f824f129a0a25e61383b01cec
-  data.tar.gz: c69809b3ce6618fc593dd8897938e5f34d8788c9
+  metadata.gz: bb133ea037943a10f5732ebcb2418ff01eb3664d
+  data.tar.gz: be31d122d267c510391b7813a662e2a8eb212d9f
 SHA512:
-  metadata.gz: 28f6f85ab7471792a741658f83a1a1b522359da8bed3e4bd5f9e9a4cf71d9e28e80fe1a087fc459bd9c4c58afbde4cb797ceb0732d7a3980556c2c973bf7838e
-  data.tar.gz: 2e71c5e388fc0c7bb727f057219e6376b4a2fe80a645738fef539ced75d1099227a27c8ac786b2c8c160c98e99fc99b22a2e0404dc414d7b3a0f2276b1e9bd7a
+  metadata.gz: d1deea6577862b637989fc13e783434a5120cfa6fd4c1b6d004fc25bcdc045316b45386f060eea5be0f0273655f2cd56ba0acee22e50a183eaf54422083fb729
+  data.tar.gz: e52dce445ee7da4fbad81137af4b8c6eb3a77e1b3700b45a11290c80d87ca8dfe1fa519c313c2ced88c293eac23b0dc410a20535715015d0293bfbec53b3bf59

data/CHANGES.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## Version 1.3.0
+
+Released on March 26, 2021
+
+Add:
+- 'activesupport' as a runtime dependency
+
+Drop:
+- 'rails' as a runtime dependency
+
+## 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
+
+New:
+- Full RSpec failure dump to stderr if any test fails when running tests with Dox::Formatter
+- Support any payload format with pretty formatting for JSON and XML (based on `content-type` header)
+
+Fix:
+- Ignore subdomain request header in headers output
+
+
+## Version 1.0.1
+
+Released on June 10, 2017
+
+New:
+- Add Rake tasks for generating documentation to Readme
+
+Fix:
+- Fix printing request body for test examples
+
+
 ## Version 1.0.0
 
 Released on May 6, 2017

data/Gemfile

@@ -5,4 +5,4 @@ gemspec
 
 rails_version = ENV['RAILS_VERSION'] || '5.0.1'
 
-gem 'rails', "~> #{rails_version}"
+gem 'activesupport', "~> #{rails_version}"

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:
 
@@ -19,7 +19,7 @@ Add this line to your application's Gemfile:
 
 ```ruby
 group :test do
-  gem 'dox', require: 'false'
+  gem 'dox', require: false
 end
 ```
 
@@ -47,7 +47,7 @@ $ gem install dox
 and configure rspec with this:
 
 ``` ruby
-Rspec.configure do |config|
+RSpec.configure do |config|
   config.after(:each, :dox) do |example|
     example.metadata[:request] = request
     example.metadata[:response] = response
@@ -242,13 +242,46 @@ end
 ### Generate documentation
 Documentation is generated in 2 steps:
 
-1. generate API Blueprint markdown with dox command:
-```bundle exec dox spec/controllers/api/v1 > docs.md```
+1. generate API Blueprint markdown:
+```bundle exec rspec spec/controllers/api/v1 -f Dox::Formatter --order defined --tag dox --out docs.md```
 
 2. render HTML with some renderer, for example, with Aglio:
 ```aglio -i docs.md -o docs.html```
 
 
+#### Use rake tasks
+It's recommendable to write a few rake tasks to make things easier. Here's an example:
+
+```ruby
+namespace :api do
+  namespace :doc do
+    desc 'Generate API documentation markdown'
+    task :md do
+      require 'rspec/core/rake_task'
+
+      RSpec::Core::RakeTask.new(:api_spec) do |t|
+        t.pattern = 'spec/controllers/api/v1/'
+        t.rspec_opts = "-f Dox::Formatter --order defined --tag dox --out public/api/docs/v1/apispec.md"
+      end
+
+      Rake::Task['api_spec'].invoke
+    end
+
+    task html: :md do
+      `aglio -i public/api/docs/v1/apispec.md -o public/api/docs/v1/index.html`
+    end
+
+    task open: :html do
+      `open public/api/docs/v1/index.html`
+    end
+
+    task publish: :md do
+      `apiary publish --path=public/api/docs/v1/apispec.md --api-name=doxdemo`
+    end
+  end
+end
+```
+
 #### Renderers
 You can render the HTML yourself with one of the renderers:
 
@@ -264,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/dox.gemspec

@@ -13,6 +13,8 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/infinum/dox'
   spec.license       = 'MIT'
 
+  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)
@@ -26,6 +28,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
+  spec.add_runtime_dependency 'activesupport', '>= 4.0'
   spec.add_development_dependency 'bundler', '~> 1.11'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
@@ -33,5 +36,4 @@ Gem::Specification.new do |spec|
   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,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/action.rb

@@ -30,7 +30,8 @@ module Dox
       end
 
       def path_params
-        @path_params ||= request.path_parameters.symbolize_keys.except(:action, :controller, :format)
+        @path_params ||=
+          request.path_parameters.symbolize_keys.except(:action, :controller, :format, :subdomain)
       end
 
       def template_path_params

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
 
@@ -15,10 +14,12 @@ module Dox
         @response = response
       end
 
-      def request_parameters
-        request.parameters
-               .except(*request.path_parameters.keys.map(&:to_s))
-               .except(*request.query_parameters.keys.map(&:to_s))
+      def request_body
+        @request_body ||= format_content(request, request_content_type)
+      end
+
+      def response_body
+        @response_body ||= format_content(response, response_content_type)
       end
 
       def request_identifier
@@ -44,9 +45,26 @@ 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]
+        request.path.presence || request.fullpath.split('?')[0]
       end
 
       attr_reader :desc, :request, :response

data/lib/dox/formatter.rb

@@ -1,11 +1,12 @@
 require 'rspec/core'
 require 'rspec/core/formatters/base_formatter'
+require 'rspec/core/formatters/console_codes'
 
 module Dox
   class Formatter < RSpec::Core::Formatters::BaseFormatter
     extend Forwardable
 
-    RSpec::Core::Formatters.register self, :example_passed, :stop
+    RSpec::Core::Formatters.register self, :example_passed, :stop, :dump_summary
 
     def initialize(output)
       super
@@ -17,8 +18,18 @@ module Dox
       move_example_to_passed if current_example.document?
     end
 
-    def stop(_notification)
-      printer.print(passed_examples)
+    def stop(notification)
+      if notification.failed_examples.any?
+        $stderr.puts(notification.fully_formatted_failed_examples)
+      else
+        printer.print(passed_examples)
+      end
+    end
+
+    def dump_summary(summary)
+      return if summary.failed_examples.none?
+      $stderr.puts(summary.fully_formatted)
+      exit(-1)
     end
 
     private

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

@@ -1,3 +1,5 @@
+require 'rexml/document'
+
 module Dox
   module Printers
     class ExamplePrinter < BasePrinter
@@ -14,7 +16,7 @@ module Dox
       def print_example_request
         @output.puts example_request_title
         @output.puts example_request_headers
-        return unless example.request_parameters.present?
+        return unless example.request_body.present?
 
         @output.puts example_request_body
       end
@@ -52,7 +54,7 @@ module Dox
 
     + Body
 
-#{indent_lines(12, pretty_json(example.request_parameters))}
+#{indent_lines(12, example.request_body)}
         HEREDOC
       end
 
@@ -77,22 +79,10 @@ module Dox
 
     + Body
 
-#{indent_lines(12, pretty_json(safe_json_parse(example.response_body)))}
+#{indent_lines(12, example.response_body)}
         HEREDOC
       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 print_headers(headers)
         headers.map do |key, value|
           "#{key}: #{value}"

data/lib/dox/version.rb

@@ -1,3 +1,3 @@
 module Dox
-  VERSION = '1.0.0'
+  VERSION = '1.3.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dox
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Melita Kokot
@@ -9,8 +9,22 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-05-06 00:00:00.000000000 Z
+date: 2021-03-26 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -109,20 +123,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4.0'
 description: 
 email:
 - melita.kokot@gmail.com
@@ -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
@@ -187,7 +192,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="