SmarfDoc

(Formerly 'DocYoSelf')

Too many docs spoil the broth.

SmarfDoc lets you turn your controller tests into API docs without making changes to your test suite or how you write tests.

Pop it into your test suite and watch it amaze.

Time for this project was provided by my employer, SmashingBoxes. What a great place to work!

Gem Installation in Rails

In your gemfile add the following to your test group:

gem 'smarf_doc', group: :test, github: 'RickCarlino/smarf_doc'

Installation differs for RSpec/Minitest, so scroll to the appropriate section for guidance.

Rspec Installation

Add this to your rails_helper.rb It should go outside of other blocks (Do not place it inside the RSpec.configure block).

SmarfDoc.config do |c|
  c.template_file = 'spec/template.md.erb'
  c.output_file   = 'api_docs.md'
end

Add the following line to spec_helper.rb inside the RSpec.configure block

config.after(:suite) { SmarfDoc.finish! }

It should look like this

RSpec.configure do |config|
  # Existing code
  config.after(:suite) { SmarfDoc.finish! }
end

To run on all controller tests

Add this to your spec_helper.rb

config.after(:each, type: :controller) do
  SmarfDoc.run!(request, response)
end

The whole file should look like this

RSpec.configure do |config|
  # Existing code
  config.after(:each, type: :controller) do
    SmarfDoc.run!(request, response)
  end
  config.after(:suite) { SmarfDoc.finish! }
end

To run on only select tests

Just add SmarfDoc.run!(request, response) to specific tests

it "responds with 200" do
  get :index
  expect(response).to be_success
  SmarfDoc.run!(request, response)
end

Minitest Installation

Add the code from below to test_helper.rb:

class ActiveSupport::TestCase
  # Already existing code
  SmarfDoc.config do |c|
    c.template_file = 'test/template.md.erb'
    c.output_file   = 'api_docs.md'
  end
  # More code
end

MiniTest::Unit.after_tests { SmarfDoc.finish! }

To run on all controller tests

Add this to test_helper.rb as well:

class ActionController::TestCase < ActiveSupport::TestCase
  def teardown
    SmarfDoc.run!(request, response)
  end
end

Your code should look like this:

class ActiveSupport::TestCase
  # Already existing code
  SmarfDoc.config do |c|
    c.template_file = 'test/template.md.erb'
    c.output_file   = 'api_docs.md'
  end
  # More code
end

class ActionController::TestCase < ActiveSupport::TestCase
  def teardown
    SmarfDoc.run!(request, response)
  end
end

MiniTest::Unit.after_tests { SmarfDoc.finish! }

To run on only select tests

Just add SmarfDoc.run!(request, response) to specific tests

def get_index
  get :index
  assert response.status == 200
  SmarfDoc.run!(request, response)
end

Setting a template

If you copied the code from above, SmarfDoc will look for a template file located at either test/template.md.erb or spec/template.md.erb, depending on your test suite. This template may be customized to fit your needs.

<%= request.method %>
<%= request.path %>
<%= request.params %>
<%= response.body %>
<%= information[:message] %>
<%= note %>

Where to find the docs

By default, the docs are output to api_docs.md in the root of the Rails project. You can change this by altering the config in test_helper.rb or rails_helper.rb.

Additional Features

Skipping documentation on tests

To leave certain tests out of the documentation, just add SmarfDoc.skip to the test.

it "responds with 200" do
  SmarfDoc.skip
  # test code
end

Adding information and notes

SmarfDoc will log all requests and responses by default, but you can add some optional parameters as well.

it "responds with 200" do
  SmarfDoc.note("This endpoint prefers butterscotch")
  # test code
end

OR

it "responds with 200" do
  SmarfDoc.information(:message, "This endpoint only responds on Tuesdays")
  # test code
end

You can store any information with :message or any other key you can think of. To access information in the template, just use <%= information[:message] %>