rspec-document_requests 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c8a8b92b750aba417d7ef6d9eef52520817c53e4
-  data.tar.gz: 536922a6d9a9d571fe3b3378bcc4b6875d830e19
+  metadata.gz: 4fedfef2a8965ead1fee4d9cb58371e3ea061814
+  data.tar.gz: f6712172151b7e9ba4a8c8897ccfdcfd4c25c5df
 SHA512:
-  metadata.gz: 2dc3124c74cdba5eec489570d43b6f4539a3c705dc073c67651c3bb96f080d31df753c463d79a35689547051fbc4b5f765c608f9301dde9c50a74f764fffd93e
-  data.tar.gz: 02af6f9b8c38d2723c2ec5b31b6816e130f20e318ef50f4cdde2dde5418622bef382ed1a928f78da57d5f755b904fdff24e4eaaa9e805c8f8d022abb0b6d5cfe
+  metadata.gz: 50c3b3868f1a0a7c32851ddab4eba661901ff0a7675ebbc50d34b9854396ccff66939f50a23fd3378d051b3f028d6668c19a9d350758da37600a1eb3390368ec
+  data.tar.gz: 4fc2781de76cc5ed2fdda452a19079604e95a20dcac27023d96b2da05de2aed597bb1283fd4f6b9084fc98cd229ad2e5b03df6acd1ee5a816b142de6624996c3

data/README.md

@@ -104,8 +104,8 @@ RSpec.describe "Session resource", type: :request, doc: true do
     before do
       explain do
         request do # No request explanation
-          parameter 'session[username]', "The username", required: true, type: 'string'
-          parameter 'session[password]', required: true, type: 'string' # No explanation
+          parameter 'session[username]', "The username", required: true,           type: 'string'
+          parameter 'session[password]',                 required: "when not SSO", type: 'string' # No explanation
           header 'Content-Type', ... # you get the point
         end
         response do # No response explanation
@@ -124,6 +124,46 @@ end
 **NOTE:** Explaining response parameters only works when this gem can
 parse the response body, see [here](#configuration) how to configure it.
 
+### Reference
+
+#### Example Group Metadatas
+
+(The hash you pass to `describe`/`context`).
+
+| Symbol        | Meaning |
+|---------------|---------|
+| `doc`         | When set to `true`, all requests in the example group (`describe`/`context`) are automatically documented. Use `doc: false` to override a parent example group. |
+| `explanation` | When set, this will be written below the title of the example group (`describe`/`context`) (depending on the writer). Use this to further explain the meaning of the request in your API. **NOTE:** grouped example groups (see `group_levels`) will not show their explanation in the default markdown writer. |
+
+#### DSL
+
+These functions are available from within your example (inside the `it`, `specify`, `before`, `after`, `around`).
+
+**NOTE:** This is only available inside example groups that have the `doc: true` metadata.
+
+| Method   | Meaning |
+|-------------------|---------|
+| `nodoc`  | Skips documentation for the rest of this example. When given a block, only skips requests made inside the block. Use this to skip specific requests that are used to prepare the request, or use the `doc: false` metadata on the entire example group. |
+| `explain`| Receives a block in which you can explain your request and its response. Inside the block, see [Explain Block](#explain-block). |
+
+##### Explain Block
+
+These methods are used inside the block passed to `explain`.
+
+| Method     | Meaning |
+|------------|---------|
+| `request`  | Receives an optional parameter that describes the meaning of this request to the entire test sequence. Also receives an optional block, see [Request/Response Block](#requestresponse-block). |
+| `response` | Receives an optional parameter that describes the meaning of this request's response to the entire test sequence. Also receives an optional block, see [Request/Response Block](#requestresponse-block). |
+
+###### Request/Response Block
+
+These methods are used inside the block passed to `request` and `response` within the `explain` block.
+
+| Method      | Meaning |
+|-------------|---------|
+| `parameter` | Receives a string that is the name of the parameter, use `[]` for nested arrays & objects. Receives an additional optional string that describes the parameter, and a hash with these optional keys: `:required`, and `:type`. **NOTE:** This only works in response when the response is parsed, see [Configuration's](#configuration) `response_parser` to make sure it does. |
+| `header`    | Receives a string that is the name of the header, use `[]` for nested arrays & objects. Receives an additional optional string that describes the header, and a hash with these optional keys: `:required`, and `:type`. |
+
 ### Configuration
 
 These are the possible configurations:
@@ -153,12 +193,26 @@ RSpec::DocumentRequests.configure do |config|
     end
   }
 
+  # Request parameters
   config.include_request_parameters  = nil # nil means not used
   config.exclude_request_parameters  = []
   config.hide_request_parameters     = [] # Displays '...' instead of actual value
+  config.enforce_explain_request_parameters = false # Raise error if an unexplained included parameter is used
+  # Request headers
+  config.include_request_headers  = nil # nil means not used
+  config.exclude_request_headers  = []
+  config.hide_request_headers     = [] # Displays '...' instead of actual value
+  config.enforce_explain_request_headers = false
+  # Response parameters
   config.include_response_parameters = nil
   config.exclude_response_parameters = []
   config.hide_response_parameters    = []
+  config.enforce_explain_response_parameters = false
+  # Response headers
+  config.include_response_headers = nil
+  config.exclude_response_headers = []
+  config.hide_response_headers    = []
+  config.enforce_explain_response_headers = false
 end
 ```
 
@@ -236,7 +290,8 @@ The gem works, but it's missing some basics:
 
 * Unit tests (specs).
 * Example generated documentations.
-* More writers (see `lib/rspec/document_requests/writers/base.rb`).
+* More writers (see [lib/rspec/document_requests/writers/base.rb](lib/rspec/document_requests/writers/base.rb)).
+* More default response parsers (see [lib/rspec/document_requests/configuration.rb](lib/rspec/document_requests/configuration.rb)).
 
 So...
 

data/lib/rspec/document_requests/configuration.rb

@@ -24,6 +24,7 @@ module RSpec
           add_property :"include_#{side}_#{part}", nil
           add_property :"exclude_#{side}_#{part}", []
           add_property :"hide_#{side}_#{part}", []
+          add_property :"enforce_explain_#{side}_#{part}", false
         end
       end
 

data/lib/rspec/document_requests/dsl.rb

@@ -2,19 +2,18 @@ module RSpec
   module DocumentRequests
     module DSL
       class << self
-        attr_accessor :documented_requests, :currently_documented_example
+        attr_accessor :documented_requests
       end
       self.documented_requests = []
-      self.currently_documented_example = nil
 
       [:get, :post, :patch, :put, :delete, :head].each do |method|
         define_method(method) do |path, parameters = nil, headers_or_env = nil|
           result = super(path, parameters, headers_or_env)
 
-          if not @document_request_prevented and DSL.currently_documented_example
+          if not @document_requests_prevented and @currently_documented_example
             DSL.documented_requests << Request.new(
               explanation:        document_request_explanation,
-              example:            DSL.currently_documented_example,
+              example:            @currently_documented_example,
               method:             method.to_s.upcase,
               path:               path,
               request_parameters: parameters,
@@ -37,11 +36,14 @@ module RSpec
       end
 
       def nodoc
-        @document_request_prevented = true
-        begin
-          yield
-        ensure
-          @document_request_prevented = false
+        was_prevented = @document_requests_prevented
+        @document_requests_prevented = true
+        if block_given?
+          begin
+            yield
+          ensure
+            @document_requests_prevented = false if not was_prevented
+          end
         end
       end
     end
@@ -54,8 +56,8 @@ RSpec.configure do |config|
     config.run_all_when_everything_filtered = false
 
     config.after(:suite) { RSpec::DocumentRequests::Builder.new }
-    config.before { |ex| RSpec::DocumentRequests::DSL.currently_documented_example = ex }
-    config.after { |ex| RSpec::DocumentRequests::DSL.currently_documented_example = nil }
+    config.before(doc: true) { |ex| @currently_documented_example = ex }
+    config.after(doc: true) { |ex| @currently_documented_example = nil }
   end
 
   config.include RSpec::DocumentRequests::DSL, doc: true

data/lib/rspec/document_requests/request.rb

@@ -2,12 +2,13 @@ module RSpec
   module DocumentRequests
     class Request
       class Parameter
-        attr_accessor :message, :required, :type, :value
-        def initialize(message = nil, required: false, type: nil, value: nil)
+        attr_accessor :message, :required, :type, :value, :generated
+        def initialize(message = nil, required: false, type: nil, value: nil, generated: false)
           @message = message
           @required = required
           @type = type
           @value = value
+          @generated = generated
         end
       end
 
@@ -33,46 +34,41 @@ module RSpec
 
       private
 
-      def self.filter_values(name)
-        define_method(name) do
-          values = instance_variable_get(:"@#{name}")
-          next values if values.nil?
+      def filter_values(name)
+        values = instance_variable_get(:"@#{name}")
+        return values if values.nil?
 
-          included_values = DocumentRequests.configuration.send(:"include_#{name}")
-          excluded_values = DocumentRequests.configuration.send(:"exclude_#{name}")
-          hidden_values = DocumentRequests.configuration.send(:"hide_#{name}")
+        included_values = DocumentRequests.configuration.send(:"include_#{name}")
+        excluded_values = DocumentRequests.configuration.send(:"exclude_#{name}")
+        hidden_values = DocumentRequests.configuration.send(:"hide_#{name}")
+        enforce = DocumentRequests.configuration.send(:"enforce_explain_#{name}")
 
-          values.select! do |k, v|
-            next false if included_values and included_values.exclude?(k)
-            next false if excluded_values.include?(k)
-            values[k].value = "..." if hidden_values.include?(k)
-            true
-          end
-          values
+        unexplained = []
+        values.select! do |k, v|
+          next false if included_values and included_values.exclude?(k)
+          next false if excluded_values.include?(k)
+          unexplained << k if v.generated
+          v.value = "..." if hidden_values.include?(k)
+          true
         end
+        raise "Unexplained parameters used: #{unexplained.join(", ")}" if enforce and unexplained.any?
+        values
       end
 
-      public
-
-      filter_values :request_parameters
-      filter_values :request_headers
-      filter_values :response_parameters
-      filter_values :response_headers
-
-      private
-
       def process_request_parameters(parameters, prefix: nil)
         @request_parameters = {}
         process_parameters(parameters, @request_parameters, explanation: @explanation.request.parameters)
+        filter_values :request_parameters
       end
 
       def process_request_headers(headers)
         @request_headers = {}
         headers.each do |name, value|
-          @request_headers[name] = @explanation.request.headers[name] || Parameter.new
+          @request_headers[name] = @explanation.request.headers[name] || Parameter.new(generated: true)
           @request_headers[name].value = value
         end
         @explanation.request.headers.each { |name, header| @request_headers[name] ||= header }
+        filter_values :request_headers
       end
 
       def process_response_parameters(parameters = nil)
@@ -81,20 +77,22 @@ module RSpec
           @response_parameters = {}
           process_parameters(@parsed_response, @response_parameters, explanation: @explanation.response.parameters)
         end
+        filter_values :response_parameters
       end
 
       def process_response_headers
         @response_headers = {}
         @response.headers.each do |name, value|
-          @response_headers[name] = @explanation.response.headers[name] || Parameter.new
+          @response_headers[name] = @explanation.response.headers[name] || Parameter.new(generated: true)
           @response_headers[name].value = value
         end
         @explanation.response.headers.each { |name, header| @response_headers[name] ||= header }
+        filter_values :response_headers
       end
 
       def process_parameters(input, output, explanation:, prefix: nil)
         input.each do |key, value|
-          name = prefix ? "#{prefix}[#{key}]" : key
+          name = prefix ? "#{prefix}[#{key}]" : key.to_s
           case value
             when Hash
               process_parameters(value, output, explanation: explanation, prefix: name)
@@ -110,11 +108,11 @@ module RSpec
                 end
               end
               if base_values.any?
-                output[name] ||= explanation[name] || Parameter.new
+                output[name] ||= explanation[name] || Parameter.new(generated: true)
                 output[name].value = [output[name].value, base_values.to_s].compact.join(", ")
               end
             else
-              output[name] ||= explanation[name] || Parameter.new
+              output[name] ||= explanation[name] || Parameter.new(generated: true)
               output[name].value = [output[name].value, value].compact.join(", ")
           end
         end

data/lib/rspec/document_requests/version.rb

@@ -1,5 +1,5 @@
 module RSpec
   module DocumentRequests
-    VERSION = "1.2.1"
+    VERSION = "1.3.0"
   end
 end

data/lib/rspec/document_requests/writers/markdown.rb

@@ -44,7 +44,7 @@ module RSpec
             @file.puts "| Name | Type | Required? | Value |   |"
             @file.puts "|------|------|-----------|-------|---|"
             parameters.each do |name, parameter|
-              @file.puts "| #{name}  | #{parameter.type}  | #{"Required" if parameter.required}  | #{parameter.value}  | #{parameter.message}  |"
+              @file.puts "| #{name}  | #{parameter.type}  | #{parameter.required || false}  | #{parameter.value}  | #{parameter.message}  |"
             end
             @file.puts
           end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-document_requests
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Oded Niv
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-06-24 00:00:00.000000000 Z
+date: 2015-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-rails