rspec_api_documentation 4.8.0 → 4.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fdd16f01648ad082b801d8fd30ebc1cd06e55fd8
-  data.tar.gz: 51d343a6cf25688c651d1631ae060410cdb53b4b
+  metadata.gz: 16b47e6bedc1c86cc5e418233eca8b80d16b5628
+  data.tar.gz: e1da890616a2fa4cf6a8ff8c44eff5977abc32f6
 SHA512:
-  metadata.gz: 6e2c63b4378da2efa410296c6133649210f4685ceb04a0ea612e91e690e69894099c220d83f01e9a5b5d77581bb2e0aa1c37b8e21b6bbda8e6440ad1411bafd4
-  data.tar.gz: bb6622522c0dda680a95e7f56666d1266fb9dc793c38a02bd9e3cb3368b317859cff1360d33ac9e87d9953180f05e606eee1320096906084a63d77b1aaf88b59
+  metadata.gz: c16d4338f5d6e06f1c913a951c1370b31f2e6c85a6aef38a593d5fbd332226ad99c9fae76207e9bed5089500010a5b588a123e0354cdef25d057cbc0483a1933
+  data.tar.gz: 03ef3fbf5306d2951fa6f3b82f08e2679306069e791ef9bf5d30f58693dbb83528bb78009821cc4b26fb1da166c33620c1e5d327c9d91f8008bd45afa93eead4

data/lib/rspec_api_documentation.rb

@@ -57,6 +57,7 @@ module RspecApiDocumentation
     autoload :TextileExample
     autoload :MarkdownIndex
     autoload :MarkdownExample
+    autoload :SlateIndex
     autoload :SlateExample
   end
 

data/lib/rspec_api_documentation/curl.rb

@@ -76,7 +76,7 @@ module RspecApiDocumentation
     def filter_headers(headers)
       if !@config_headers_to_filer.empty?
         headers.reject do |header|
-          @config_headers_to_filer.include?(format_header(header))
+          @config_headers_to_filer.map(&:downcase).include?(format_header(header).downcase)
         end
       else
         headers

data/lib/rspec_api_documentation/dsl/endpoint.rb

@@ -1,6 +1,7 @@
 require 'rspec/core/formatters/base_formatter'
 require 'rack/utils'
 require 'rack/test/utils'
+require 'rspec_api_documentation/dsl/endpoint/params'
 
 module RspecApiDocumentation::DSL
   # DSL methods available inside the RSpec example.
@@ -63,11 +64,7 @@ module RspecApiDocumentation::DSL
     end
 
     def params
-      parameters = example.metadata.fetch(:parameters, {}).inject({}) do |hash, param|
-        set_param(hash, param)
-      end
-      parameters.deep_merge!(extra_params)
-      parameters
+      Params.new(self, example, extra_params).call
     end
 
     def header(name, value)
@@ -99,22 +96,14 @@ module RspecApiDocumentation::DSL
       rspec_api_documentation_client.status
     end
 
-    def in_path?(param)
-      path_params.include?(param)
-    end
-
-    def path_params
-      example.metadata[:route].scan(/:(\w+)/).flatten
-    end
-
     def path
       example.metadata[:route].gsub(/:(\w+)/) do |match|
         if extra_params.keys.include?($1)
           delete_extra_param($1)
         elsif respond_to?($1)
-          send($1)
+          escape send($1)
         else
-          match
+          escape match
         end
       end
     end
@@ -146,26 +135,5 @@ module RspecApiDocumentation::DSL
       @extra_params.delete(key.to_sym) || @extra_params.delete(key.to_s)
     end
 
-    def set_param(hash, param)
-      key = param[:name]
-
-      keys = [param[:scope], key].flatten.compact
-      method_name = keys.join('_')
-
-      return hash if in_path?(method_name)
-
-      unless respond_to?(method_name)
-        method_name = key
-        return hash unless respond_to?(method_name)
-      end
-
-      hash.deep_merge(build_param_hash(keys, method_name))
-    end
-
-    def build_param_hash(keys, method_name)
-      value = keys[1] ? build_param_hash(keys[1..-1], method_name) : send(method_name)
-      { keys[0].to_s => value }
-    end
-
   end
 end

data/lib/rspec_api_documentation/dsl/endpoint/params.rb

@@ -0,0 +1,30 @@
+require 'rspec_api_documentation/dsl/endpoint/set_param'
+
+module RspecApiDocumentation
+  module DSL
+    module Endpoint
+      class Params
+        attr_reader :example_group, :example
+
+        def initialize(example_group, example, extra_params)
+          @example_group = example_group
+          @example = example
+          @extra_params = extra_params
+        end
+
+        def call
+          parameters = example.metadata.fetch(:parameters, {}).inject({}) do |hash, param|
+            SetParam.new(self, hash, param).call
+          end
+          parameters.deep_merge!(extra_params)
+          parameters
+        end
+
+      private
+
+        attr_reader :extra_params
+
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/dsl/endpoint/set_param.rb

@@ -0,0 +1,62 @@
+module RspecApiDocumentation
+  module DSL
+    module Endpoint
+      class SetParam
+        def initialize(parent, hash, param)
+          @parent = parent
+          @hash = hash
+          @param = param
+        end
+
+        def call
+          return hash if path_params.include?(path_name)
+          return hash unless method_name
+
+          hash.deep_merge build_param_hash(key_scope || [key])
+        end
+
+      private
+
+        attr_reader :parent, :hash, :param
+        delegate :example_group, :example, to: :parent
+
+        def key
+          @key ||= param[:name]
+        end
+
+        def key_scope
+          @key_scope ||= param[:scope] && Array(param[:scope]).dup.push(key)
+        end
+
+        def scoped_key
+          @scoped_key ||= key_scope && key_scope.join('_')
+        end
+
+        def custom_method_name
+          param[:method]
+        end
+
+        def path_name
+          scoped_key || key
+        end
+
+        def path_params
+          example.metadata[:route].scan(/:(\w+)/).flatten
+        end
+
+        def method_name
+          @method_name ||= begin
+            [custom_method_name, scoped_key, key].find do |name|
+              name && example_group.respond_to?(name)
+            end
+          end
+        end
+
+        def build_param_hash(keys)
+          value = keys[1] ? build_param_hash(keys[1..-1]) : example_group.send(method_name)
+          { keys[0].to_s => value }
+        end
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/dsl/resource.rb

@@ -50,6 +50,10 @@ module RspecApiDocumentation::DSL
         headers[name] = value
       end
 
+      def explanation(text)
+        safe_metadata(:resource_explanation, text)
+      end
+
       private
 
       def field_specification(name, *args)

data/lib/rspec_api_documentation/example.rb

@@ -42,6 +42,10 @@ module RspecApiDocumentation
       respond_to?(:response_fields) && response_fields.present?
     end
 
+    def resource_explanation
+      metadata[:resource_explanation] || nil
+    end
+
     def explanation
       metadata[:explanation] || nil
     end
@@ -63,7 +67,7 @@ module RspecApiDocumentation
       requests.each.with_index do |request_hash, index|
         next unless request_hash.key?(key)
         headers = request_hash[key]
-        request_hash[key] = headers.select{ |key, _| headers_to_include.include?(key) }
+        request_hash[key] = headers.select{ |key, _| headers_to_include.map(&:downcase).include?(key.downcase) }
         requests[index] = request_hash
       end
     end

data/lib/rspec_api_documentation/views/markdown_example.rb

@@ -8,6 +8,14 @@ module RspecApiDocumentation
         self.template_name = "rspec_api_documentation/markdown_example"
       end
 
+      def parameters
+        super.map do |parameter|
+          parameter.merge({
+            :required => parameter[:required] ? 'true' : 'false',
+          })
+        end
+      end
+
       def extension
         EXTENSION
       end

data/lib/rspec_api_documentation/views/markup_example.rb

@@ -23,7 +23,8 @@ module RspecApiDocumentation
       end
 
       def filename
-        basename = description.downcase.gsub(/\s+/, '_').gsub(Pathname::SEPARATOR_PAT, '')
+        special_chars = /[<>:"\/\\|?*]/
+        basename = description.downcase.gsub(/\s+/, '_').gsub(special_chars, '')
         basename = Digest::MD5.new.update(description).to_s if basename.blank?
         "#{basename}.#{extension}"
       end
@@ -31,14 +32,15 @@ module RspecApiDocumentation
       def parameters
         super.each do |parameter|
           if parameter.has_key?(:scope)
-            scope = Array(parameter[:scope]).each_with_index.map do |scope, index|
-              if index == 0
-                scope
-              else
-                "[#{scope}]"
-              end
-            end.join
-            parameter[:scope] = scope
+            parameter[:scope] = format_scope(parameter[:scope])
+          end
+        end
+      end
+
+      def response_fields
+        super.each do |response_field|
+          if response_field.has_key?(:scope)
+            response_field[:scope] = format_scope(response_field[:scope])
           end
         end
       end
@@ -71,6 +73,16 @@ module RspecApiDocumentation
           "#{k}: #{v}"
         end.join("\n")
       end
+
+      def format_scope(unformatted_scope)
+        Array(unformatted_scope).each_with_index.map do |scope, index|
+          if index == 0
+            scope
+          else
+            "[#{scope}]"
+          end
+        end.join
+      end
     end
   end
 end

data/lib/rspec_api_documentation/views/slate_example.rb

@@ -6,25 +6,11 @@ module RspecApiDocumentation
         self.template_name = "rspec_api_documentation/slate_example"
       end
 
-      def curl_with_linebreaks
-        requests.map {|request| request[:curl].lines }.flatten.map do |line|
-          line.rstrip.gsub("\t", '  ').gsub(' ', ' ').gsub('\\', '\')
-        end.join "<br>"
-      end
-
-      def explanation_with_linebreaks
-        explanation.gsub "\n", "<br>\n"
-      end
-
-      def write
-        File.open(configuration.docs_dir.join("#{FILENAME}.#{extension}"), 'w+') do |file|
-          file.write "# #{configuration.api_name}\n\n"
-          index.examples.sort_by!(&:description) unless configuration.keep_source_order
-
-          index.examples.each do |example|
-            markup_example = markup_example_class.new(example, configuration)
-            file.write markup_example.render
-          end
+      def parameters
+        super.map do |parameter|
+          parameter.merge({
+            :required => parameter[:required] == 'true' ? true : false,
+          })
         end
       end
     end

data/lib/rspec_api_documentation/views/slate_index.rb

@@ -0,0 +1,6 @@
+module RspecApiDocumentation
+  module Views
+    class SlateIndex < MarkdownIndex
+    end
+  end
+end

data/lib/rspec_api_documentation/writers/index_helper.rb

@@ -6,7 +6,7 @@ module RspecApiDocumentation
       def sections(examples, configuration)
         resources = examples.group_by(&:resource_name).inject([]) do |arr, (resource_name, examples)|
           ordered_examples = configuration.keep_source_order ? examples : examples.sort_by(&:description)
-          arr.push(:resource_name => resource_name, :examples => ordered_examples)
+          arr.push(:resource_name => resource_name, :examples => ordered_examples, resource_explanation: examples.first.resource_explanation)
         end
         configuration.keep_source_order ? resources : resources.sort_by { |resource| resource[:resource_name] }
       end

data/lib/rspec_api_documentation/writers/json_writer.rb

@@ -47,6 +47,7 @@ module RspecApiDocumentation
       def section_hash(section)
         {
           :name => section[:resource_name],
+          :explanation => section[:resource_explanation],
           :examples => section[:examples].map { |example|
             {
               :description => example.description,
@@ -87,6 +88,7 @@ module RspecApiDocumentation
       def as_json(opts = nil)
         {
           :resource => resource_name,
+          :resource_explanation => resource_explanation,
           :http_method => http_method,
           :route => route,
           :description => description,

data/lib/rspec_api_documentation/writers/slate_writer.rb

@@ -2,28 +2,50 @@ module RspecApiDocumentation
   module Writers
 
     class SlateWriter < MarkdownWriter
-      FILENAME = '_generated_examples'
+      EXTENSION = 'html.md'
+      FILENAME = 'index'
 
       def self.clear_docs(docs_dir)
         FileUtils.mkdir_p(docs_dir)
         FileUtils.rm Dir[File.join docs_dir, "#{FILENAME}.*"]
       end
 
+      def markup_index_class
+        RspecApiDocumentation::Views::SlateIndex
+      end
+
       def markup_example_class
         RspecApiDocumentation::Views::SlateExample
       end
 
       def write
         File.open(configuration.docs_dir.join("#{FILENAME}.#{extension}"), 'w+') do |file|
-          file.write "# #{configuration.api_name}\n\n"
-          index.examples.sort_by!(&:description) unless configuration.keep_source_order
 
-          index.examples.each do |example|
-            markup_example = markup_example_class.new(example, configuration)
-            file.write markup_example.render
+          file.write %Q{---\n}
+          file.write %Q{title: "#{configuration.api_name}"\n}
+          file.write %Q{language_tabs:\n}
+          file.write %Q{  - json: JSON\n}
+          file.write %Q{  - shell: cURL\n}
+          file.write %Q{---\n\n}
+
+          IndexHelper.sections(index.examples, @configuration).each do |section|
+
+            file.write "# #{section[:resource_name]}\n\n"
+            section[:examples].sort_by!(&:description) unless configuration.keep_source_order
+
+            section[:examples].each do |example|
+              markup_example = markup_example_class.new(example, configuration)
+              file.write markup_example.render
+            end
+
           end
+
         end
       end
+
+      def extension
+        EXTENSION
+      end
     end
   end
 end

data/templates/rspec_api_documentation/html_example.mustache

@@ -10,6 +10,10 @@
   <body>
     <div class="container">
       <h1>{{resource_name}} API</h1>
+      {{# resource_explanation }}
+
+        <p class="explanation">{{{ resource_explanation }}}</p>
+      {{/ resource_explanation }}
 
       <div class="article">
         <h2>{{ description }}</h2>

data/templates/rspec_api_documentation/html_index.mustache

@@ -14,6 +14,10 @@
   {{# sections }}
   <div class="article">
     <h2>{{ resource_name }}</h2>
+    {{# resource_explanation }}
+
+      <p class="explanation">{{{ resource_explanation }}}</p>
+    {{/ resource_explanation }}
 
     <ul>
       {{# examples }}

data/templates/rspec_api_documentation/markdown_example.mustache

@@ -1,4 +1,8 @@
 # {{ resource_name }} API
+{{# resource_explanation }}
+
+{{{ resource_explanation }}}
+{{/ resource_explanation }}
 
 ## {{ description }}
 
@@ -10,10 +14,11 @@
 {{# has_parameters? }}
 
 ### Parameters
-{{# parameters }}
 
-Name : {{ name }}{{# required }} *- required -*{{/ required }}
-Description : {{ description }}
+| Name | Description | Required | Scope |
+|------|-------------|----------|-------|
+{{# parameters }}
+| {{ name }} | {{ description }} | {{ required }} | {{ scope }} |
 {{/ parameters }}
 
 {{/ has_parameters? }}

data/templates/rspec_api_documentation/markdown_index.mustache

@@ -2,6 +2,10 @@
 
 {{# sections }}
 ## {{ resource_name }}
+{{# resource_explanation }}
+
+{{{ resource_explanation }}}
+{{/ resource_explanation }}
 
 {{# examples }}
 * [{{ description }}]({{ dirname }}/{{ filename }})

data/templates/rspec_api_documentation/slate_example.mustache

@@ -1,5 +1,9 @@
 ## {{ description }}
 
+{{# explanation }}
+{{{ explanation }}}
+{{/ explanation }}
+
 ### Request
 
 #### Endpoint
@@ -13,11 +17,6 @@
 
 `{{ http_method }} {{ route }}`
 
-{{# explanation }}
-
-{{{ explanation_with_linebreaks }}}
-{{/ explanation }}
-
 #### Parameters
 
 {{# requests}}
@@ -78,9 +77,8 @@ None known.
 {{/ has_response_fields? }}
 
 {{# curl }}
-
-### cURL
-
-<code>{{{ curl_with_linebreaks }}}</code>
+```shell
+{{{ curl }}}
+```
 {{/ curl }}
 {{/ requests}}

data/templates/rspec_api_documentation/textile_example.mustache

@@ -1,4 +1,8 @@
 h1. {{ resource_name }} API
+{{# resource_explanation }}
+
+{{{ resource_explanation }}}
+{{/ resource_explanation }}
 
 h2. {{ description }}
 

data/templates/rspec_api_documentation/textile_index.mustache

@@ -2,6 +2,10 @@ h1. {{ api_name }}
 
 {{# sections }}
 h2. {{ resource_name }}
+{{# resource_explanation }}
+
+{{{ resource_explanation }}}
+{{/ resource_explanation }}
 
 {{# examples }}
 * "{{ description }}":{{ dirname }}/{{ filename }}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec_api_documentation
 version: !ruby/object:Gem::Version
-  version: 4.8.0
+  version: 4.9.0
 platform: ruby
 authors:
 - Chris Cahoon
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-25 00:00:00.000000000 Z
+date: 2016-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -19,9 +19,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,9 +26,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -277,6 +271,8 @@ files:
 - lib/rspec_api_documentation/dsl.rb
 - lib/rspec_api_documentation/dsl/callback.rb
 - lib/rspec_api_documentation/dsl/endpoint.rb
+- lib/rspec_api_documentation/dsl/endpoint/params.rb
+- lib/rspec_api_documentation/dsl/endpoint/set_param.rb
 - lib/rspec_api_documentation/dsl/resource.rb
 - lib/rspec_api_documentation/example.rb
 - lib/rspec_api_documentation/headers.rb
@@ -293,6 +289,7 @@ files:
 - lib/rspec_api_documentation/views/markup_example.rb
 - lib/rspec_api_documentation/views/markup_index.rb
 - lib/rspec_api_documentation/views/slate_example.rb
+- lib/rspec_api_documentation/views/slate_index.rb
 - lib/rspec_api_documentation/views/textile_example.rb
 - lib/rspec_api_documentation/views/textile_index.rb
 - lib/rspec_api_documentation/writers/append_json_writer.rb