had 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8db267458f5bae36246d3f0a3b3b479d94884460
+  data.tar.gz: 72b0dd4604f3b8bd240cdf96e459d5ef99047c1c
+SHA512:
+  metadata.gz: cdbcd9ff09cc012638b003ffc176dd17d19808b1daff08048837d1919ed3d5350f818d7eba34f4e50b819366da9d10294530441c50d43b11aff1750b0c044935
+  data.tar.gz: 3951a608143dffd695a2447514d7baf47f676911009e3806e692526699b0f0a4a8887400a83d7450976efcdac3dcb605f556ced6fe00323bee88f8bf1b8e6983

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.idea
+.rvmrc

data/.ruby-version

@@ -0,0 +1 @@
+2.3.4

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in had.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2017 nsheremet
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,139 @@
+# Had
+
+Had is Hanami Api Documentation. Gem generates API documentation from your integration tests written with `rspec` for [Hanami](https://hanamirb.org).
+
+This is fork of [`reqres_rspec`](https://github.com/reqres-api/reqres_rspec) gem and worked implemantation for Hanami.
+
+## Installation
+
+### 1) Gem
+
+Just add this gem to `Gemfile` of your API Application
+
+    gem 'had', group: :test
+
+And then execute:
+
+    $ bundle install
+
+If necessary, add `require "had"` to your `spec/spec_helper.rb` file
+
+## Usage
+
+by default `had` is not active (this may be configured!). To activate it, run `rspec` with
+
+`HAD_RUN=1 bundle exec rspec --order=defined`
+
+Documentation will be put into your application's `/doc` folder
+
+### Sample controller action
+
+```ruby
+  # @description creates Category from given parameters
+  # description text may be multiline
+  # @param category[title] required String Category title
+  # @param category[weight] in which order Category will be shown
+  # param text may also be multiline
+  # @method GET
+  # @path /example/path
+  # @host example.com
+  def call(params)
+    # action code
+  end
+```
+
+Description param text is started with `@description` and may be multiline.
+Each param text is started with `@param` and first word will be param name, then optionally `required`, then optionally type (`Integer`, `String` etc), and finally param description, which may be multiline as well.
+
+### Sample rspec test
+
+```ruby
+  it 'validates params', :skip_had do
+    ...
+  end
+
+  context 'With valid params' do
+    it 'bakes pie' do
+      ...
+    end
+  end
+
+  context 'With invalid params', :skip_had do
+    it 'returns errors' do
+      ...
+    end
+  end
+```
+
+ By default all examples will be added to docs. A context of examples (`context` and `describe` blocks) or any particular examples may be excluded from docs with option `:skip_had`
+
+ Doc will use full example description, as a title for each separate spec
+
+If you want to group examples in another way, you can do something like:
+
+```ruby
+describe 'Something', had_section: 'Foo' do
+  context 'valid params', had_title: 'Bakes Pie' do
+    it 'works' do
+      ...
+    end
+
+    it 'tires baker', had_title: 'Tires baker' do
+      ...
+    end
+  end
+end
+```
+
+## Configuration
+
+```ruby
+Had.configure do |c|
+  c.templates_path = './spec/support/reqres/templates' # Path to custom templates
+  c.output_path = 'some path' # by default it will use doc/reqres
+  c.formatters = %w(MyCustomFormatter) # List of custom formatters, these can be inherited from Had::Formatters::HTML
+  c.title = 'My API Documentation' # Title for your documentation
+end
+```
+
+## Custom Formatter example
+
+```ruby
+class CustomAPIDoc < Had::Formatters::HTML
+  private
+  def write
+    # Copy assets
+    %w(styles images components scripts).each do |folder|
+      FileUtils.cp_r(path(folder), output_path)
+    end
+
+    # Generate general pages
+    @pages = {
+      'index.html'          => 'Introduction',
+      'authentication.html' => 'Authentication',
+      'filtering.html'      => 'Filtering, Sorting and Pagination',
+      'locations.html'      => 'Locations',
+      'files.html'          => 'Files',
+      'external-ids.html'   => 'External IDs',
+    }
+
+    @pages.each do |filename, _|
+      @current_page = filename
+      save filename, render("pages/#{filename}")
+    end
+
+    # Generate API pages
+    @records.each do |record|
+      @record       = record
+      @current_page = @record[:filename]
+      save "#{record[:filename]}.html", render('spec.html.erb')
+    end
+  end
+end
+```
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/had.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'had/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'had'
+  spec.version       = Had::VERSION
+  spec.authors       = ['nsheremet']
+  spec.email         = ['nazariisheremet@gmail.com']
+  spec.description   = %q{Had is Hanami Api Documentation gem. This gem generates API documentation for integration tests written with RSpec for Hanami}
+  spec.summary       = %q{Generates API documentation for integration tests written with RSpec for Hanami}
+  spec.homepage      = 'https://github.com/nsheremet/had'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'coderay'
+  spec.add_dependency 'mime-types'
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
+end

data/lib/had/collector.rb

@@ -0,0 +1,337 @@
+module Had
+  class Collector
+    # Contains spec values read from rspec example, request and response
+    attr_accessor :records
+
+    # Param importances
+    PARAM_IMPORTANCES = %w[required optional conditional deprecated]
+
+    # Param types
+    # NOTE: make sure sub-strings go at the end
+    PARAM_TYPES = ['Boolean', 'Text', 'Float', 'DateTime', 'Date', 'File', 'UUID', 'Hash',
+                   'Array of Integer', 'Array of String', 'Array', 'Integer', 'String',
+                   'Email']
+
+    # Exclude replacement in symbolized path
+    EXCLUDE_PARAMS = %w[limit offset format description controller action]
+
+    # response headers contain many unnecessary information,
+    # everything from this list will be stripped
+    EXCLUDE_RESPONSE_HEADER_PATTERNS = %w[
+      Cache-Control
+      ETag
+      X-Content-Type-Options
+      X-Frame-Options
+      X-Request-Id
+      X-Runtime
+      X-UA-Compatible
+      X-XSS-Protection
+      Vary
+      Last-Modified
+    ]
+
+    # request headers contain many unnecessary information,
+    # everything that match items from this list will be stripped
+    EXCLUDE_REQUEST_HEADER_PATTERNS = %w[
+      action_controller.
+      action_dispatch
+      CONTENT_LENGTH
+      HTTP_COOKIE
+      HTTP_HOST
+      HTTP_ORIGIN
+      HTTP_USER_AGENT
+      HTTPS
+      ORIGINAL_FULLPATH
+      ORIGINAL_SCRIPT_NAME
+      PATH_INFO
+      QUERY_STRING
+      rack.
+      raven.requested_at
+      RAW_POST_DATA
+      REMOTE_ADDR
+      REQUEST_METHOD
+      REQUEST_URI
+      ROUTES_
+      SCRIPT_NAME
+      SERVER_NAME
+      SERVER_PORT
+      sinatra.commonlogger
+      sinatra.route
+      HTTP_X_API
+      warden
+      devise.mapping
+    ]
+
+    def initialize
+      self.records = []
+    end
+
+    # collects spec data for further processing
+    def collect(spec, example, request, response)
+      # TODO: remove boilerplate code
+      return if request.nil? || response.nil? || !defined?(request.params.env)
+
+      description = query_parameters = backend_parameters = 'not available'
+      params = []
+
+      if request.params.env && (request_params = request.params)
+        action = request.class.name.split('::').last
+        controller = request.class.name.split('::')[-2]
+        description, additional_info = get_action_description(controller, action)
+        # description = request.class.to_s
+        params = get_action_params(controller, action)
+        query_parameters = request_params.to_h.reject { |p| %w[controller action format].include? p }
+        backend_parameters = request_params.to_h.reject { |p| !%w[controller action format].include? p }
+      end
+
+      ex_gr = spec.class.example.metadata[:example_group]
+      section = ex_gr[:description]
+      while !ex_gr.nil? do
+        section = ex_gr[:description]
+        ex_gr = ex_gr[:parent_example_group]
+      end
+
+      self.records << {
+        filename: prepare_filename_for(spec.class.metadata),
+        group: spec.class.metadata[:had_section] || section,
+        title: example_title(spec, example),
+        description: description,
+        params: params,
+        request: {
+          host: additional_info['host'],
+          url: additional_info['host'] + additional_info['path'],
+          path: additional_info['path'],
+          symbolized_path: additional_info['host'] + additional_info['path'],
+          method: additional_info['method'],
+          query_parameters: query_parameters,
+          backend_parameters: backend_parameters,
+          body: request.instance_variable_get("@_body"),
+          content_length: query_parameters.to_s.size,
+          content_type: request.content_type,
+          headers: read_request_headers(request),
+          accept: (request.accept rescue nil)
+        },
+        response: {
+          code: response.first,
+          body: response.last.last,
+          headers: read_response_headers(response),
+          format: format(response)
+        }
+      }
+
+      # cleanup query params
+      begin
+        body_hash = JSON.parse(self.records.last[:request][:body])
+        query_hash = self.records.last[:request][:query_parameters]
+        diff = Hash[*((query_hash.size > body_hash.size) ? query_hash.to_a - body_hash.to_a : body_hash.to_a - query_hash.to_a).flatten]
+        self.records.last[:request][:query_parameters] = diff
+      rescue
+      end
+    end
+
+    def prepare_filename_for(metadata)
+      description = metadata[:description]
+      example_group = if metadata.key?(:example_group)
+                        metadata[:example_group]
+                      else
+                        metadata[:parent_example_group]
+                      end
+
+      if example_group
+        [prepare_filename_for(example_group), description].join('/')
+      else
+        description
+      end.downcase.gsub(/[\W]+/, '_').gsub('__', '_').gsub(/^_|_$/, '')
+    end
+
+    # sorts records alphabetically
+    def sort
+      self.records.sort! do |x,y|
+        comp = x[:request][:symbolized_path] <=> y[:request][:symbolized_path]
+        comp.zero? ? (x[:title] <=> y[:title]) : comp
+      end
+    end
+
+    private
+
+    def example_title(spec, example)
+      t = prepare_description(example.metadata, :had_title) ||
+          spec.class.example.full_description
+      t.strip
+    end
+
+    def prepare_description(payload, key)
+      payload[key] &&
+        ->(x) { (x.is_a?(TrueClass) || x == '') ? payload[:description] : x }.call(payload[key])
+    end
+
+    # read and cleanup response headers
+    # returns Hash
+    def read_response_headers(response)
+      raw_headers = response[1]
+      headers = {}
+      EXCLUDE_RESPONSE_HEADER_PATTERNS.each do |pattern|
+        raw_headers = raw_headers.reject { |h| h if h.start_with? pattern }
+      end
+      raw_headers.each do |key, val|
+        headers.merge!(cleanup_header(key) => val)
+      end
+      headers
+    end
+
+    def format(response)
+      case response[1]['Content-Type']
+      when %r{text/html}
+        :html
+      when %r{application/json}
+        :json
+      else
+        :json
+      end
+    end
+
+    # read and cleanup request headers
+    # returns Hash
+    def read_request_headers(request)
+      headers = {}
+      request.params.env.keys.each do |key|
+        if EXCLUDE_REQUEST_HEADER_PATTERNS.all? { |p| !key.to_s.start_with? p }
+          headers.merge!(cleanup_header(key) => request.params.env[key])
+        end
+      end
+      headers
+    end
+
+    # replace each first occurrence of param's value in the request path
+    #
+    # Example:
+    #   request path = /api/users/123
+    #   id = 123
+    #   symbolized path => /api/users/:id
+    #
+    def get_symbolized_path(request)
+      request_path = request.env['REQUEST_URI'] || request.path
+      request_params =
+        request.env['action_dispatch.request.parameters'] ||
+        request.env['rack.request.form_hash'] ||
+        request.env['rack.request.query_hash']
+
+      if request_params
+        request_params
+          .except(*EXCLUDE_PARAMS)
+          .select { |_, value| value.is_a?(String) }
+          .each { |key, value| request_path.sub!("/#{value}", "/:#{key}") if value.to_s != '' }
+      end
+
+      request_path
+    end
+
+    # returns action comments taken from controller file
+    # example TODO
+    def get_action_comments(controller, action)
+      lines = File.readlines(File.join(Had.root, 'app', 'controllers', "#{controller}", "#{action}.rb"))
+
+      action_line = nil
+      lines.each_with_index do |line, index|
+        if line.match(/\s*def call/)
+          action_line = index
+          break
+        end
+      end
+
+      if action_line
+        comment_lines = []
+        request_additionals = {}
+        was_comment = true
+        while action_line > 0 && was_comment
+          action_line -= 1
+
+          if lines[action_line].match(/\s*#/)
+            comment_lines << lines[action_line].strip
+          else
+            was_comment = false
+          end
+        end
+
+        comment_lines.reverse
+      else
+        ['not found']
+      end
+    rescue Errno::ENOENT
+      ['not found']
+    end
+
+    # returns description action comments
+    # example TODO
+    def get_action_description(controller, action)
+      comment_lines = get_action_comments(controller, action)
+      info = {}
+      description = []
+      comment_lines.each_with_index do |line, index|
+        if line.match(/\s*#\s*@description/) # @description blah blah
+          description << line.gsub(/\A\s*#\s*@description/, '').strip
+          comment_lines[(index + 1)..-1].each do |multiline|
+            if !multiline.match(/\s*#\s*@param/)
+              description << "\n"
+              description << multiline.gsub(/\A\s*#\s*/, '').strip
+            else
+              break
+            end
+          end
+        elsif line.match(/\s*# @method/)
+          info['method'] = line.split(' ').last
+        elsif line.match(/\s*# @path/)
+          info['path'] = line.split(' ').last
+        elsif line.match(/\s*# @host/)
+          info['host'] = line.split(' ').last
+        end
+      end
+
+      [description.join(' '), info]
+    end
+
+    # returns params action comments
+    # example TODO
+    def get_action_params(controller, action)
+      comment_lines = get_action_comments(controller, action)
+
+      comments_raw = []
+      has_param = false
+      comment_lines.each do |line|
+        if line.match(/\s*#\s*@param/) # @param id required Integer blah blah
+          has_param = true
+          comments_raw << ''
+        end
+        if has_param
+          line = line.gsub(/\A\s*#\s*@param/, '')
+          line = line.gsub(/\A\s*#\s*/, '').strip
+
+          comments_raw.last << "\n" unless comments_raw.last.empty?
+          comments_raw.last << line
+        end
+      end
+
+      comments = []
+      comments_raw.each do |comment|
+        match_data = comment.match(/(?<name>[a-z0-9A-Z_\[\]]+)?\s*(?<required>#{PARAM_IMPORTANCES.join('|')})?\s*(?<type>#{PARAM_TYPES.join('|')})?\s*(?<description>.*)/m)
+
+        if match_data
+          comments << {
+            name: match_data[:name],
+            required: match_data[:required],
+            type: match_data[:type],
+            description: match_data[:description]
+          }
+        else
+          comments << { description: comment }
+        end
+      end
+
+      comments
+    end
+
+    def cleanup_header(key)
+      key.to_s.sub(/^HTTP_/, '').underscore.split('_').map(&:capitalize).join('-')
+    end
+  end
+end

data/lib/had/configuration.rb

@@ -0,0 +1,52 @@
+require 'pry'
+require 'fileutils'
+
+module Had
+  extend self
+
+  def configure
+    yield configuration
+  end
+
+  def configuration
+    @configuration ||= Configuration.new
+  end
+
+  def logger
+    Logger.new(STDOUT)
+  end
+
+  def root
+    configuration.root
+  end
+
+  class Configuration
+    DEFAULT_FORMATTERS = %w(html json)
+
+    def initialize
+      Had.logger.level = Logger::INFO
+
+      if ENV['APP_ROOT'].nil?
+        raise 'APP_ROOT is not defined'
+      else
+        @root = ENV['APP_ROOT']
+      end
+
+      @templates_path = File.expand_path('../templates', __FILE__)
+      @output_path = File.join(@root, '/doc/had')
+      FileUtils.mkdir_p @output_path
+
+      requested_formats = (ENV['HAD_FORMATTERS'].to_s).split(',')
+      requested_formats.sort_by!{|fmt| [DEFAULT_FORMATTERS.index(fmt), fmt]}
+      @formatters = requested_formats.empty? ? %w(html) : requested_formats
+
+      @title = 'Hanami Api Documentation'
+    end
+
+    attr_accessor :templates_path
+    attr_accessor :output_path
+    attr_accessor :title
+    attr_accessor :formatters
+    attr_reader :root
+  end
+end

data/lib/had/formatters/base.rb

@@ -0,0 +1,35 @@
+module Had
+  module Formatters
+    class Base
+      def initialize(records)
+        @records = records
+        @output_path = Had.configuration.output_path
+        @logger = Had.logger
+      end
+      attr_reader :logger, :output_path, :records
+
+      def process
+        cleanup
+        write
+      end
+
+    private
+
+      def write
+        raise 'Not Implemented'
+      end
+
+      def cleanup_pattern
+        '**/*'
+      end
+
+      def cleanup
+        unless Dir.exist?(output_path)
+          FileUtils.mkdir_p(output_path)
+          logger.info "#{output_path} was recreated"
+        end
+        FileUtils.rm_rf(Dir.glob("#{output_path}/#{cleanup_pattern}"), secure: true)
+      end
+    end
+  end
+end

data/lib/had/formatters/html.rb

@@ -0,0 +1,45 @@
+require 'coderay'
+
+module Had
+  module Formatters
+    class HTML < Base
+    private
+      def write
+        files = {
+          'rspec_doc_table_of_content.html' => 'header.erb',
+          'index.html' => 'index.erb',
+          'panel.html' => 'panel.erb'
+        }
+
+        files.each { |filename, template| save(filename, render(template)) }
+
+        @records.each do |record|
+          @record = record
+          save "rspec_doc_#{record[:filename]}.html", render('spec.erb')
+        end
+      end
+
+      def cleanup_pattern
+        '*.html'
+      end
+
+      def path(filename)
+        File.join(Had.configuration.templates_path, filename)
+      end
+
+      def render(filename, arguments = {})
+        eval <<-RUBY
+          #{ arguments.map {|k, v| "#{k} = #{v}"}.join("\n") }
+          ERB.new(File.open(path(filename)).read).result(binding)
+        RUBY
+      rescue Exception => e
+        logger.error "Reqres::Formatters::HTML.render exception #{e.message}"
+      end
+
+      def save(filename, data)
+        File.write(File.join(output_path, filename), data)
+        logger.info "Reqres::Formatters::HTML saved #{path(filename)}"
+      end
+    end
+  end
+end