rspec-document_requests 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 231e877c797beff56b6713d86e7247cf7e31ea72
-  data.tar.gz: 06f5cbf0269fa7c3d5f772425081619327ef7ab7
+  metadata.gz: 7c1fd117650183a8e2b17f41acfeb19bcd011251
+  data.tar.gz: 582ddbaa7fd602d131b676747a10b084172fb479
 SHA512:
-  metadata.gz: efc0c7d69098f85741a3cbc27e395e6addb62510226ac4398a4c27e624d3c910e8eeb4dbb488c5d27e0e1219c1852eda4b14749569ec7239392789cc9f7cf116
-  data.tar.gz: 3cff5a55338cf639810fc696855c0aa9089f78e5629969447c7f5ddfa6eb157a7cf07c32fa419b9c1ffb17e65698c4ba4ec4a22f3e7b6683bed850fe8442f0d1
+  metadata.gz: e31e5dcc0518b3c6305ad60a8ac1f34dd2047ccd4a5759aaf4ffebc7a4b79764cce964edc29ca069338314e21a31e9bab892a269d2d8feeb63c50217f97bdd8b
+  data.tar.gz: 8952825398234193dc0dad866685978a5fd4e5e601bbd9a3258e91dc53ed6ed8835b6612df2acaa2993100972656849640e8b8e2c34f7e3f67e7f9eff829a103

data/README.md

@@ -44,6 +44,8 @@ require 'rspec/document_requests/dsl' # <- this line
 
 ### Marking code to document
 
+**NOTE:** The `nodoc` DSL is not available in example groups (`describe`/`context`) without `doc: true`.
+
 In your example group (`describe`/`context`), simply add the `doc: true` metadata:
 
 ```ruby
@@ -85,7 +87,7 @@ also exclude any specs without `doc: true` metadata to make this run faster.
 
 ### Explaining the request
 
-**NOTE:** This DSL is not available in `doc: false` example groups (`describe`/`context`).
+**NOTE:** The `explain` DSL is not available in example groups (`describe`/`context`) without `doc: true`.
 
 Just before your request, it's a good idea to explain (everything is optional):
 
@@ -93,20 +95,20 @@ Just before your request, it's a good idea to explain (everything is optional):
 # spec/requests/session_spec.rb
 
 RSpec.describe "Session resource", type: :request, doc: true do
-  describe "Create session" do
+  describe "Create session", explanation: "This is how you create a session." do
     before do
-      explain "Creating the user"
+      explain { request "Creating a user" }
       post "/users", user: { username: "myuser", password: "123123" }
     end
 
     before do
-      explain do # No request explanation
-        request 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
           header 'Content-Type', ... # you get the point
         end
-        response do
+        response do # No response explanation
           parameter 'message', "Message from the server", required: true # No type
           parameter 'session_id', "The session ID" # Not required and no type
           header 'Set-Cookie', ...

data/lib/rspec/document_requests/builder.rb

@@ -30,8 +30,9 @@ module RSpec
           @writer = config.writer.new(file)
           write_breadcrumb
           write_title
-          @current.ungrouped_children.each { |child| write_child(child) }
+          @current.ungrouped_children.each { |child| write_child(child, last: child == @current.ungrouped_children.last) }
           write_recursive_requests(@current)
+          @writer.close
         end
 
         @current.ungrouped_children.each do |child|
@@ -44,12 +45,18 @@ module RSpec
         missing_levels = []
         if not child == @current
           missing = child
-          missing_levels.unshift(missing.description) while (missing = missing.parent) and missing != @current
+          missing_levels.unshift(missing) while (missing = missing.parent) and missing != @current
+        end
+        missing_levels = missing_levels.map do |organized_entry|
+          {
+            description: organized_entry.metadata[:description],
+            explanation: metadata_explanation(organized_entry.metadata),
+          }
         end
 
         child.example_requests.to_a.uniq { |e,| e.example_group }.each do |example, requests|
           write_example_title(example, missing_levels: missing_levels) unless child == @current
-          requests.each { |request| write_request(request, missing_levels: missing_levels) }
+          requests.each { |request| write_request(request) }
         end
 
         child.grouped_children.each_with_index do |grandchild, i|
@@ -57,6 +64,10 @@ module RSpec
         end
       end
 
+      def metadata_explanation(metadata)
+        metadata[:explanation] if metadata[:parent_example_group].nil? or metadata[:explanation] != metadata[:parent_example_group][:explanation]
+      end
+
       def write_breadcrumb
         current = @current
         parent_tree = []
@@ -67,7 +78,7 @@ module RSpec
         parent_path = Pathname.new('.').join(*parent_tree.length.times.map { '..' })
         parent_tree.each do |parent|
           @writer.breadcrumb(
-            description: parent.description,
+            description: parent.metadata[:description],
             filename:    parent_path.join(parent.filename).sub_ext(config.writer::EXTENSION),
             last:        parent == @current.parent,
           )
@@ -76,22 +87,37 @@ module RSpec
       end
 
       def write_title
-        @writer.title(@current.description)
+        metadata = @current.metadata
+        @writer.title(description: metadata[:description], explanation: metadata_explanation(metadata))
       end
 
-      def write_child(child)
+      def write_child(child, last:)
         @writer.child(
-          description: child.description,
+          description: child.metadata[:description],
           filename:    @current.filename.join(child.filename).sub_ext(config.writer::EXTENSION),
+          last:        last,
         )
       end
 
       def write_example_title(example, missing_levels:)
-        @writer.example_title(example.example_group.metadata[:description], missing_levels: missing_levels)
+        metadata = example.example_group.metadata
+        @writer.example_title(description: metadata[:description], explanation: metadata_explanation(metadata), missing_levels: missing_levels)
       end
 
-      def write_request(request, missing_levels:)
-        @writer.request(request, missing_levels: missing_levels)
+      def write_request(request)
+        # request
+        @writer.request.title(request.explanation.request.message)
+        @writer.request.path(request.method, request.path)
+        @writer.request.parameters(request.request_parameters) if request.request_parameters.present?
+        @writer.request.body(request.request_body)             if request.request_body.present?
+        @writer.request.headers(request.request_headers)       if request.request_headers.present?
+        # response
+        @writer.response.title(request.explanation.response.message)
+        @writer.response.status(request.response.status, request.response.status_message)
+        @writer.response.content_type(request.response.content_type)
+        @writer.response.parameters(request.response_parameters) if request.response_parameters.present?
+        @writer.response.body(request.response.body)             if request.response.body.present?
+        @writer.response.headers(request.response_headers)       if request.response_headers.present?
       end
     end
   end

data/lib/rspec/document_requests/dsl.rb

@@ -28,9 +28,8 @@ module RSpec
         end
       end
 
-      def explain(message = nil, &block)
-        document_request_explanation.message = message if message
-        document_request_explanation.instance_eval(&block) if block_given?
+      def explain(&block)
+        document_request_explanation.instance_eval(&block)
       end
 
       def document_request_explanation

data/lib/rspec/document_requests/explanation.rb

@@ -2,7 +2,7 @@ module RSpec
   module DocumentRequests
     class Explanation
       class Side
-        attr_accessor :parameters, :headers
+        attr_accessor :message, :parameters, :headers
 
         def initialize
           @parameters = {}
@@ -18,22 +18,22 @@ module RSpec
         end
       end
 
-      attr_accessor :message
-
       def initialize
         @request = Side.new
         @response = Side.new
       end
 
-      def request(&block)
-        @request.instance_eval(&block) if block_given?
-        @request
+      def self.build_side(side)
+        define_method(side) do |message = nil, &block|
+          instance = instance_variable_get(:"@#{side}")
+          instance.message = message if message
+          instance.instance_eval(&block) if block_given?
+          instance
+        end
       end
 
-      def response(&block)
-        @response.instance_eval(&block) if block_given?
-        @response
-      end
+      build_side :request
+      build_side :response
     end
   end
 end

data/lib/rspec/document_requests/organized_request.rb

@@ -1,19 +1,22 @@
 module RSpec
   module DocumentRequests
     class OrganizedRequest
-      attr_reader :parent, :filename, :description, :example_requests, :children, :levels
-      def initialize(description:, parent: nil)
-        @description = description
+      attr_reader :parent, :metadata, :example_requests, :children, :levels
+      def initialize(metadata, parent: nil)
+        @metadata = metadata
         @parent = parent
-        @filename = Pathname.new(DocumentRequests.configuration.filename_generator.call(description))
         @example_requests = Hash.new { |h, k| h[k] = [] }
         @children = {}
         @levels = Hash.new { |h, k| h[k] = 0 }
         @parent.increase_level(self) if @parent
       end
 
-      def child(description)
-        @children[DocumentRequests.configuration.filename_generator.call(description)] ||= OrganizedRequest.new(description: description, parent: self)
+      def filename
+        @filename ||= Pathname.new(DocumentRequests.configuration.filename_generator.call(@metadata[:description]))
+      end
+
+      def child(metadata)
+        @children[DocumentRequests.configuration.filename_generator.call(metadata[:description])] ||= OrganizedRequest.new(metadata, parent: self)
       end
 
       def increase_level(child)
@@ -44,7 +47,7 @@ module RSpec
 
           organized_request = root
           metadata_tree.each do |metadata|
-            organized_request = organized_request.child(metadata[:description])
+            organized_request = organized_request.child(metadata)
           end
           organized_request.example_requests[request.example] << request
         end

data/lib/rspec/document_requests/version.rb

@@ -1,5 +1,5 @@
 module RSpec
   module DocumentRequests
-    VERSION = "1.1.0"
+    VERSION = "1.2.0"
   end
 end

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

@@ -4,28 +4,96 @@ module RSpec
       class Base
         #EXTENSION = ".something"
 
+        attr_reader :request, :response
+
         def initialize(file)
           @file = file
+          @request = self.class::Request.new(file)
+          @response = self.class::Response.new(file)
         end
 
         def breadcrumb(description:, filename:, last:)
           raise NotImplementedError
         end
 
-        def title(description)
+        def title(description:, explanation:)
           raise NotImplementedError
         end
 
-        def child(description:, filename:)
+        def child(description:, filename:, last:)
           raise NotImplementedError
         end
 
-        def request_title(description, missing_levels:)
+        # missing_levels: [{ description: "", explanation: "" || nil }, ...]
+        def example_title(description:, explanation:, missing_levels:)
           raise NotImplementedError
         end
 
-        def request(request, missing_levels:)
-          raise NotImplementedError
+        def close
+          @request.close
+          @response.close
+        end
+
+        class Request
+          def initialize(file)
+            @file = file
+          end
+
+          def title(message)
+            raise NotImplementedError
+          end
+
+          def path(method, path)
+            raise NotImplementedError
+          end
+
+          def parameters(parameters)
+            raise NotImplementedError
+          end
+
+          def body(body)
+            raise NotImplementedError
+          end
+
+          def headers(headers)
+            raise NotImplementedError
+          end
+
+          def close
+          end
+        end
+
+        class Response
+          def initialize(file)
+            @file = file
+          end
+
+          def title(message)
+            raise NotImplementedError
+          end
+
+          def status(status, message)
+            raise NotImplementedError
+          end
+
+          def content_type(content_type)
+            raise NotImplementedError
+          end
+
+          def parameters(parameters)
+            raise NotImplementedError
+          end
+
+          def body(body)
+            raise NotImplementedError
+          end
+
+          def headers(headers)
+            raise NotImplementedError
+          end
+
+          def close
+          end
         end
       end
     end

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

@@ -14,100 +14,115 @@ module RSpec
           end
         end
 
-        def title(description)
+        def title(description:, explanation:)
           @file.puts "# #{description}"
           @file.puts
+          if explanation
+            @file.puts explanation
+            @file.puts
+          end
         end
 
-        def child(description:, filename:)
+        def child(description:, filename:, last:)
           @file.puts "* [#{description}](#{filename})"
+          @file.puts if last
         end
 
-        def example_title(description, missing_levels:)
-          @file.puts "## #{missing_levels.map { |l| "#{l} > " }.join} #{description}"
+        def example_title(description:, explanation:, missing_levels:)
+          @file.puts "## #{missing_levels.map { |l| "#{l[:description]} > " }.join}#{description}"
           @file.puts
+          if explanation
+            @file.puts explanation
+            @file.puts
+          end
         end
 
-        def request(request, missing_levels:)
-          @file.write <<FILE
-### Request#{" (#{request.explanation.message})" if request.explanation.message}
-
-    #{request.method} #{request.path}
-
-FILE
+        module ParametersTable
+          private
 
-          if request.request_parameters and request.request_parameters.any?
-            @file.write <<FILE
-#### Parameters
-
-FILE
-            parameters_table(request.request_parameters)
-          elsif request.request_body
-            @file.write <<FILE
-#### Body
-
-    #{request.request_body}
-
-FILE
+          def parameters_table(parameters)
+            @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}  |"
+            end
+            @file.puts
           end
+        end
 
-          if request.request_headers.any?
-            @file.write <<FILE
-#### Headers
+        class Request < Base::Request
+          include ParametersTable
 
-FILE
-            parameters_table(request.request_headers)
+          def title(message)
+            @file.puts "### Request#{" (#{message})" if message}"
+            @file.puts
           end
 
-          @file.write <<FILE
-### Response
-
-#### Status
-
-    #{request.response.status} #{request.response.status_message}
-
-#### Content-Type
-
-    #{request.response.content_type}
-
-FILE
+          def path(method, path)
+            @file.puts "    #{method} #{path}"
+            @file.puts
+          end
 
-          if request.response_parameters and request.response_parameters.any?
-            @file.write <<FILE
-#### Parameters
+          def parameters(parameters)
+            @file.puts "#### Parameters"
+            @file.puts
+            parameters_table(parameters)
+          end
 
-FILE
-            parameters_table(request.response_parameters)
+          def body(body)
+            @file.puts "#### Body"
+            @file.puts
+            @file.puts "    #{body}"
+            @file.puts
           end
 
-          @file.write <<FILE
-#### Body
+          def headers(headers)
+            @file.puts "#### Headers"
+            @file.puts
+            parameters_table(headers)
+          end
+        end
 
-    #{request.response.body}
+        class Response < Base::Response
+          include ParametersTable
 
-FILE
+          def title(message)
+            @file.puts "### Response#{" (#{message})" if message}"
+            @file.puts
+          end
 
-          if request.response_headers.any?
-            @file.write <<FILE
-#### Headers
+          def status(status, message)
+            @file.puts "#### Status"
+            @file.puts
+            @file.puts "    #{status} #{message}"
+            @file.puts
+          end
 
-FILE
-            parameters_table(request.response_headers)
+          def content_type(content_type)
+            @file.puts "#### Content-Type"
+            @file.puts
+            @file.puts "    #{content_type}"
+            @file.puts
           end
-        end
 
-        private
+          def parameters(parameters)
+            @file.puts "#### Parameters"
+            @file.puts
+            parameters_table(parameters)
+          end
 
-        def parameters_table(parameters)
-          @file.write <<FILE
-| Name | Type | Required? | Value |   |
-|------|------|-----------|-------|---|
-FILE
+          def body(body)
+            @file.puts "#### Body"
+            @file.puts
+            @file.puts "    #{body}"
+            @file.puts
+          end
 
-          parameters.each do |name, parameter|
-            @file.puts "| #{name}  | #{parameter.type}  | #{"Required" if parameter.required}  | #{parameter.value}  | #{parameter.message}  |"
+          def headers(headers)
+            @file.puts "#### Headers"
+            @file.puts
+            parameters_table(headers)
           end
-          @file.puts
         end
       end
     end

metadata

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