RSpec::DocumentRequests

gem 'rspec-document_requests'

# spec/rails_helper.rb

...
require 'rspec/rails'
require 'rspec/document_requests/dsl' # <- this line
...

# 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

# spec/requests/session_spec.rb

RSpec.describe "Session resource", type: :request, doc: true do
  describe "Create session", explanation: "This is how you create a session." do
    before do
      explain { request "Creating a user" }
      post "/users", user: { username: "myuser", password: "123123" }
    end

    before do
      explain do
        request do # No request 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
          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

# 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
  }

  # 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

# .rspec

--require document_requests_helper

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