rspec-document_requests 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 07dd25c82e673ad273e0c18f127ec929c0869b28
+  data.tar.gz: b9b67877628275e67bdf87e8d2729ca7c1babcd1
+SHA512:
+  metadata.gz: 5d09018dd25cd1e11a5a8e196bf544f93a51e211323a95930387c9245a11ecbaf152e1bcc084e4ae0a04a26fd7ded43d6a62f2ace38693dda9e05c16203b9352
+  data.tar.gz: 5162824b78e0486125a648b75c7e395842b94119f99481b4db66bccf758b6d9514f8ca73d18ab2287b19d417f52cdf9dc7810d7948436902bf76f67c9824fe78

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.2

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

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

data/README.md

@@ -0,0 +1,245 @@
+# RSpec::DocumentRequests [![Gem Version](https://badge.fury.io/rb/rspec-document_requests.svg)](http://badge.fury.io/rb/rspec-document_requests)
+
+This gem is an extension to [rspec-rails](https://github.com/rspec/rspec-rails),
+which adds the capability to automatically document requests made by your
+request specs. This will help you document your API effortlessly.
+
+This was made after checking out
+[rspec_api_documentation](https://github.com/zipmark/rspec_api_documentation),
+in which I didn't like the fact that it forces you into its own DSL (which is
+basically a small subset of RSpec DSL). If you liked it, you'll probably like
+this one more.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rspec-document_requests'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rspec-document_requests
+
+## Usage
+
+### Require
+
+Require the DSL _after_ you require `rspec/rails` (most likely in your
+`spec/rails_helper.rb`):
+
+```ruby
+# spec/rails_helper.rb
+
+...
+require 'rspec/rails'
+require 'rspec/document_requests/dsl' # <- this line
+...
+```
+
+### Marking code to document
+
+In your example group (`describe`/`context`), simply add the `doc: true` metadata:
+
+```ruby
+# spec/requests/session_spec.rb
+
+RSpec.describe "Session resource", type: :request, doc: true do
+  describe "Create session" do
+    # User creation, will not be documented in "Session resource" documentation (nodoc)
+    before do
+      nodoc { post "/users", user: { username: "myuser", password: "123123" } }
+    end
+
+    context "Correct password" do
+      before { post "/session", session: { username: "myuser", password: "123123" } }
+      it { ... }
+    end
+
+    context "Incorrect password" do
+      before { post "/session", session: { username: "myuser", password: "456456" } }
+      it { ... }
+    end
+
+    # Extra test, will not be documented (doc: false)
+    context "Incorrect username", doc: false do
+      before { post "/session", session: { username: "wronguser", password: "123123" } }
+      it { ... }
+    end
+  end
+end
+```
+
+### Running in documentation mode
+
+To prevent every rspec run deleting all your documentation, this gem only
+documents the requests when `DOC=true` environment variable is set. This will
+also exclude any specs without `doc: true` metadata to make this run faster.
+
+    DOC=true rake spec
+
+### Explaining the request
+
+**NOTE:** This DSL is not available in `doc: false` example groups (`describe`/`context`).
+
+Just before your request, it's a good idea to explain (everything is optional):
+
+```ruby
+# spec/requests/session_spec.rb
+
+RSpec.describe "Session resource", type: :request, doc: true do
+  describe "Create session" do
+    before do
+      explain "Creating the user"
+      post "/users", user: { username: "myuser", password: "123123" }
+    end
+
+    before do
+      explain do # No request explanation
+        request do
+          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
+          parameter 'message', "Message from the server", required: true # No type
+          parameter 'session_id', "The session ID" # Not required and no type
+          header 'Set-Cookie', ...
+        end
+      end
+      post "/session", session: { username: "myuser", password: "123123" }
+    end
+    it { ... }
+  end
+end
+```
+
+**NOTE:** Explaining response parameters only works when this gem can
+parse the response body, see [here](#configuration) how to configure it.
+
+### Configuration
+
+These are the possible configurations:
+
+```ruby
+# spec/document_requests_helper.rb
+
+RSpec::DocumentRequests.configure do |config|
+  # These are the default values
+
+  config.directory = "doc" # From Rails.root. CAREFUL: directory/root gets deleted!
+  config.root = "Requests" # I actually use API, figured this is a better default
+  # Example groups with less than this amount of example group (describe/context)
+  # levels under it will be grouped under its parent example group.
+  config.group_levels = 1
+  # Currently only markdown available with the gem.
+  # Contribute more by checking out lib/rspec/document_requests/writers/base.rb.
+  config.writer = RSpec::DocumentRequests:::Writers::Markdown
+  # Converts example groups (describe/context) to filenames (and directories), the default simple
+  # lower-cases and uses dash (-) for spaces.
+  config.filename_generator = -> (name) { name.downcase.gsub(/[_ ]+/, '-') }
+  # Allows showing response body as a table of parameters (with explanations).
+  # Don't forget to contribute more!
+  config.response_parser = -> (response) {
+    case
+      when response.content_type.json? then JSON.parse(response.body)
+    end
+  }
+
+  config.include_request_parameters  = nil # nil means not used
+  config.exclude_request_parameters  = []
+  config.hide_request_parameters     = [] # Displays '...' instead of actual value
+  config.include_response_parameters = nil
+  config.exclude_response_parameters = []
+  config.hide_response_parameters    = []
+end
+```
+
+Don't forget to require your file:
+
+```ruby
+# .rspec
+
+--require document_requests_helper
+
+```
+
+## REQUIRED best practices
+
+It's always a good idea to follow this best-practice, but for this gem to work
+it's necessary.
+
+The implementation documents example groups (`describe`/`context`), and not
+examples (`it`/`specify`).
+
+It is important that you do not make requests
+(`get`/`post`/`put`/`patch`/`delete`/`head`) from inside an example
+(`it`/`specify`). It will only document requests from the first example of each
+example group (`describe`/`context`).
+
+It does however work only from inside examples (`it`/`specify`)
+so requests from any form of `before`/`after`/`around` that is _not_ `:each`
+will not be documented.
+
+This best practice has other upsides other than making this gem work which I
+will not describe here. But here is a nice example for this best practice to follow:
+
+```ruby
+RSpec.describe "Some interface (class/feature/API resource)", doc: true do
+  subject { response }
+
+  describe "An interface within the interface (method/action/sub-feature)" do
+    before { post "/api/action", param: param_value }
+
+    context "Some scenario (attributes/params/prerequisite)" do
+      let(:param_value) { "scenario value" }
+
+      it { should have_http_status :ok }
+      # "body is not wrong" will not be documented
+      specify("body is not wrong") { expect(response.body).to eq "something" }
+    end
+
+    context "Another scenario" do
+      let(:param_value) { "another scenario" }
+
+      ...
+    end
+  end
+
+  context "Some scenario" do
+    before { nodoc { post "/api/scenario_prerequisite" } }
+
+    describe "An interface" do
+      before { get "/api/result" }
+
+      ...
+    end
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+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`).
+
+So...
+
+1. Fork it ( https://github.com/odedniv/rspec-document_requests/fork )
+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 a new Pull Request

data/Rakefile

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

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <http://unlicense.org/>

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rspec/document_requests"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/rspec/document_requests.rb

@@ -0,0 +1,21 @@
+require 'rspec/document_requests/version'
+
+module RSpec
+  module DocumentRequests
+    autoload :Configuration,    'rspec/document_requests/configuration'
+    autoload :Request,          'rspec/document_requests/request'
+    autoload :Explanation,      'rspec/document_requests/explanation'
+    autoload :DSL,              'rspec/document_requests/dsl'
+    autoload :OrganizedRequest, 'rspec/document_requests/organized_request'
+    autoload :Builder,          'rspec/document_requests/builder'
+    autoload :Writers,          'rspec/document_requests/writers'
+
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    def self.configure
+      yield self.configuration
+    end
+  end
+end

data/lib/rspec/document_requests/builder.rb

@@ -0,0 +1,98 @@
+module RSpec
+  module DocumentRequests
+    class Builder
+      def initialize
+        clean
+        @root = OrganizedRequest.organize
+        write
+      end
+
+      private
+
+      def config
+        DocumentRequests.configuration
+      end
+
+      def clean
+        root_directory = config.directory.join(config.filename_generator.call(config.root))
+        root_filename = root_directory.sub_ext(config.writer::EXTENSION)
+
+        root_directory.rmtree if root_directory.exist?
+        root_filename.delete if root_filename.exist?
+      end
+
+      def write(organized_request = @root, fullpath: config.directory)
+        @current = organized_request
+        @current_path = fullpath
+
+        @current_path.mkpath
+        @current_path.join(@current.filename).sub_ext(config.writer::EXTENSION).open('wb') do |file|
+          @writer = config.writer.new(file)
+          write_breadcrumb
+          write_title
+          @current.ungrouped_children.each { |child| write_child(child) }
+          write_recursive_requests(@current)
+        end
+
+        @current.ungrouped_children.each do |child|
+          # @current unusable from here on-end
+          write(child, fullpath: fullpath.join(organized_request.filename))
+        end
+      end
+
+      def write_recursive_requests(child)
+        missing_levels = []
+        if not child == @current
+          missing = child
+          missing_levels.unshift(missing.description) while (missing = missing.parent) and missing != @current
+        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) }
+        end
+
+        child.grouped_children.each_with_index do |grandchild, i|
+          write_recursive_requests(grandchild)
+        end
+      end
+
+      def write_breadcrumb
+        current = @current
+        parent_tree = []
+        parent_tree.unshift(current) while current = current.parent
+
+        return if parent_tree.empty?
+
+        parent_path = Pathname.new('.').join(*parent_tree.length.times.map { '..' })
+        parent_tree.each do |parent|
+          @writer.breadcrumb(
+            description: parent.description,
+            filename:    parent_path.join(parent.filename).sub_ext(config.writer::EXTENSION),
+            last:        parent == @current.parent,
+          )
+          parent_path = parent_path.split[0]
+        end
+      end
+
+      def write_title
+        @writer.title(@current.description)
+      end
+
+      def write_child(child)
+        @writer.child(
+          description: child.description,
+          filename:    @current.filename.join(child.filename).sub_ext(config.writer::EXTENSION),
+        )
+      end
+
+      def write_example_title(example, missing_levels:)
+        @writer.example_title(example.example_group.metadata[:description], missing_levels: missing_levels)
+      end
+
+      def write_request(request, missing_levels:)
+        @writer.request(request, missing_levels: missing_levels)
+      end
+    end
+  end
+end

data/lib/rspec/document_requests/configuration.rb

@@ -0,0 +1,35 @@
+module RSpec
+  module DocumentRequests
+    class Configuration
+      def self.add_property(name, default = nil)
+        attr_writer name
+        define_method name do
+          instance_variable_get(:"@#{name}") || default
+        end
+      end
+
+      add_property :directory, ::Rails.root.join("doc")
+      add_property :root, "Requests"
+      add_property :group_levels, 1
+      add_property :writer, Writers::Markdown
+      add_property :filename_generator, -> (name) { name.downcase.gsub(/[_ ]+/, '-') }
+      add_property :response_parser, -> (response) {
+        case
+          when response.content_type.json? then JSON.parse(response.body)
+        end
+      }
+
+      [:request, :response].each do |side|
+        [:parameters, :headers].each do |part|
+          add_property :"include_#{side}_#{part}", nil
+          add_property :"exclude_#{side}_#{part}", []
+          add_property :"hide_#{side}_#{part}", []
+        end
+      end
+
+      def directory=(directory)
+        @directory = ::Rails.root.join(directory)
+      end
+    end
+  end
+end

data/lib/rspec/document_requests/dsl.rb

@@ -0,0 +1,63 @@
+module RSpec
+  module DocumentRequests
+    module DSL
+      class << self
+        attr_accessor :documented_requests, :currently_documented_example
+      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
+            DSL.documented_requests << Request.new(
+              explanation:        document_request_explanation,
+              example:            DSL.currently_documented_example,
+              method:             method.to_s.upcase,
+              path:               path,
+              request_parameters: parameters,
+              request_headers:    headers,
+              response:           response,
+            )
+          end
+          @document_request_explanation = Explanation.new
+          DSL.currently_documented_example = nil
+
+          result
+        end
+      end
+
+      def explain(message = nil, &block)
+        document_request_explanation.message = message
+        document_request_explanation.instance_eval(&block) if block_given?
+      end
+
+      def document_request_explanation
+        @document_request_explanation ||= Explanation.new
+      end
+
+      def nodoc
+        @document_request_prevented = true
+        begin
+          yield
+        ensure
+          @document_request_prevented = false
+        end
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  if ENV['DOC']
+    config.filter_run :doc
+    config.run_all_when_everything_filtered = false
+
+    config.after(:suite) { RSpec::DocumentRequests::Builder.new }
+    config.before { |ex| RSpec::DocumentRequests::DSL.currently_documented_example = ex }
+  end
+
+  config.include RSpec::DocumentRequests::DSL, doc: true
+end

data/lib/rspec/document_requests/explanation.rb

@@ -0,0 +1,39 @@
+module RSpec
+  module DocumentRequests
+    class Explanation
+      class Side
+        attr_accessor :parameters, :headers
+
+        def initialize
+          @parameters = {}
+          @headers = {}
+        end
+
+        def parameter(name, *args)
+          @parameters[name] = Request::Parameter.new(*args)
+        end
+
+        def header(name, *args)
+          @headers[name] = Request::Parameter.new(*args)
+        end
+      end
+
+      attr_accessor :message
+
+      def initialize
+        @request = Side.new
+        @response = Side.new
+      end
+
+      def request(&block)
+        return @request if not block_given?
+        @request.instance_eval(&block)
+      end
+
+      def response(&block)
+        return @request if not block_given?
+        @response.instance_eval(&block)
+      end
+    end
+  end
+end

data/lib/rspec/document_requests/organized_request.rb

@@ -0,0 +1,56 @@
+module RSpec
+  module DocumentRequests
+    class OrganizedRequest
+      attr_reader :parent, :filename, :description, :example_requests, :children, :levels
+      def initialize(description:, parent: nil)
+        @description = description
+        @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)
+      end
+
+      def increase_level(child)
+        @grouped_children = @ungrouped_children = nil
+        @levels[child] += 1
+        @parent.increase_level(self) if @parent
+      end
+
+      def max_level
+        @levels.values.max || 0
+      end
+
+      def grouped_children
+        @grouped_children ||= @children.values.select { |child| child.max_level < DocumentRequests.configuration.group_levels }.sort_by(&:filename)
+      end
+
+      def ungrouped_children
+        @ungrouped_children ||= (@children.values - grouped_children).sort_by(&:filename)
+      end
+
+      def self.organize
+        root = OrganizedRequest.new(description: DocumentRequests.configuration.root)
+
+        DSL.documented_requests.each do |request|
+          current = request.example.example_group.metadata
+          metadata_tree = [current]
+          metadata_tree.unshift(current) while current = current[:parent_example_group]
+
+          organized_request = root
+          metadata_tree.each do |metadata|
+            organized_request = organized_request.child(metadata[:description])
+          end
+          organized_request.example_requests[request.example] << request
+        end
+
+        root
+      end
+    end
+  end
+end

data/lib/rspec/document_requests/request.rb

@@ -0,0 +1,107 @@
+module RSpec
+  module DocumentRequests
+    class Request
+      class Parameter
+        attr_accessor :message, :required, :type, :value
+        def initialize(message = nil, required: false, type: nil, value: nil)
+          @message = message
+          @required = required
+          @type = type
+          @value = value
+        end
+      end
+
+      attr_reader :explanation, :example, :method, :path
+      attr_reader :request_parameters, :request_headers
+      attr_reader :response, :parsed_response, :response_parameters, :response_headers
+      def initialize(explanation:, example:, method:, path:, request_parameters:, request_headers:, response:)
+        @explanation    = explanation
+        @example        = example
+        @method         = method
+        @path           = path
+        @response       = response
+
+        process_request_parameters(request_parameters)
+        process_request_headers(request_headers)
+        process_response_parameters
+        process_response_headers
+      end
+
+      private
+
+      def self.filter_values(name)
+        define_method(name) do
+          values = instance_variable_get(:"@#{name}")
+          next 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}")
+
+          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
+        end
+      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(request_parameters, @request_parameters, explanation: @explanation.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].value = value
+        end
+        @explanation.request.headers.each { |name, header| @request_headers[name] ||= header }
+      end
+
+      def process_response_parameters(parameters = nil)
+        @parsed_response = DocumentRequests.configuration.response_parser.call(response)
+        if @parsed_response
+          @response_parameters = {}
+          process_parameters(@parsed_response, @response_parameters, explanation: @explanation.response.parameters)
+        end
+      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].value = value
+        end
+        @explanation.response.headers.each { |name, header| @response_headers[name] ||= header }
+      end
+
+      def process_parameters(input, output, explanation:, prefix: nil)
+        input.each do |key, value|
+          name = prefix ? "#{prefix}[#{key}]" : key
+          if value.is_a?(Hash)
+            process_parameters(value, output, explanation: explanation, prefix: name)
+          else
+            output[name] = explanation[name] || Parameter.new
+            output[name].value = value
+          end
+        end
+        if prefix.nil?
+          explanation.each { |name, parameter| output[name] ||= parameter }
+        end
+      end
+    end
+  end
+end

data/lib/rspec/document_requests/version.rb

@@ -0,0 +1,5 @@
+module RSpec
+  module DocumentRequests
+    VERSION = "0.1.0"
+  end
+end

data/lib/rspec/document_requests/writers.rb

@@ -0,0 +1,8 @@
+module RSpec
+  module DocumentRequests
+    module Writers
+      autoload :Base,     'rspec/document_requests/writers/base'
+      autoload :Markdown, 'rspec/document_requests/writers/markdown'
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+module RSpec
+  module DocumentRequests
+    module Writers
+      class Base
+        #EXTENSION = ".something"
+
+        def initialize(file)
+          @file = file
+        end
+
+        def breadcrumb(description:, filename:, last:)
+          raise NotImplementedError
+        end
+
+        def title(description)
+          raise NotImplementedError
+        end
+
+        def child(description:, filename:)
+          raise NotImplementedError
+        end
+
+        def request_title(description, missing_levels:)
+          raise NotImplementedError
+        end
+
+        def request(request, missing_levels:)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+module RSpec
+  module DocumentRequests
+    module Writers
+      class Markdown < Base
+        EXTENSION = ".md"
+
+        def breadcrumb(description:, filename:, last:)
+          @file.write "[#{description}](#{filename})"
+          if not last
+            @file.write " > "
+          else
+            @file.puts
+            @file.puts
+          end
+        end
+
+        def title(description)
+          @file.puts "# #{description}"
+          @file.puts
+        end
+
+        def child(description:, filename:)
+          @file.puts "* [#{description}](#{filename})"
+        end
+
+        def example_title(description, missing_levels:)
+          @file.puts "## #{missing_levels.map { |l| "#{l} > " }.join} #{description}"
+          @file.puts
+        end
+
+        def request(request, missing_levels:)
+          @file.write <<FILE
+### Request #{"(#{request.explanation.message})" if request.explanation.message}
+
+    #{request.method} #{request.path}
+
+FILE
+
+          if request.request_parameters.any?
+            @file.write <<FILE
+
+#### Parameters
+
+FILE
+            parameters_table(request.request_parameters)
+          end
+
+          if request.request_headers.any?
+            @file.write <<FILE
+
+#### Headers
+
+FILE
+            parameters_table(request.request_headers)
+          end
+
+          @file.write <<FILE
+
+### Response
+
+#### Status
+
+    #{request.response.status} #{request.response.status_message}
+
+FILE
+
+          if request.response_parameters and request.response_parameters.any?
+            @file.write <<FILE
+#### Parameters
+
+FILE
+            parameters_table(request.response_parameters)
+          end
+
+          @file.write <<FILE
+
+#### Body
+
+    #{request.response.body}
+
+FILE
+
+          if request.response_headers.any?
+            @file.write <<FILE
+
+#### Headers
+
+FILE
+            parameters_table(request.response_headers)
+          end
+        end
+
+        private
+
+        def parameters_table(parameters)
+          @file.write <<FILE
+| Name | Type | Required? | Value | Explanation |
+|------|------|-----------|-------|-------------|
+FILE
+
+          parameters.sort.each do |name, parameter|
+            @file.puts "| #{name}  | #{parameter.type}  | #{"Required" if parameter.required}  | #{parameter.value}  | #{parameter.message}  |"
+          end
+        end
+      end
+    end
+  end
+end

data/rspec-document_requests.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rspec/document_requests/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rspec-document_requests"
+  spec.version       = RSpec::DocumentRequests::VERSION
+  spec.authors       = ["Oded Niv"]
+  spec.email         = ["oded.niv@gmail.com"]
+
+  spec.summary       = %q{Automatically documents requests generated by RSpec examples.}
+  spec.description   = %q{Use this gem to document your API with your specs.}
+  spec.homepage      = "https://github.com/odedniv/rspec-document_requests"
+  spec.license       = "UNLICENSE"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "rspec-rails", ">= 3.0"
+
+  spec.add_development_dependency "bundler", "~> 1.9"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: rspec-document_requests
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Oded Niv
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-06-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: Use this gem to document your API with your specs.
+email:
+- oded.niv@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- README.md
+- Rakefile
+- UNLICENSE
+- bin/console
+- bin/setup
+- lib/rspec/document_requests.rb
+- lib/rspec/document_requests/builder.rb
+- lib/rspec/document_requests/configuration.rb
+- lib/rspec/document_requests/dsl.rb
+- lib/rspec/document_requests/explanation.rb
+- lib/rspec/document_requests/organized_request.rb
+- lib/rspec/document_requests/request.rb
+- lib/rspec/document_requests/version.rb
+- lib/rspec/document_requests/writers.rb
+- lib/rspec/document_requests/writers/base.rb
+- lib/rspec/document_requests/writers/markdown.rb
+- rspec-document_requests.gemspec
+homepage: https://github.com/odedniv/rspec-document_requests
+licenses:
+- UNLICENSE
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.7
+signing_key: 
+specification_version: 4
+summary: Automatically documents requests generated by RSpec examples.
+test_files: []