Avocado

Avocado hooks into your Rails specs and generates a JSON file containing useful information. It sends that JSON file to a configurable URL where you can do whatever you want with it, such as display API documentation for your mobile team.

By default, Avocado comes with an Angular API viewer within Avocado::Engine.

gem "avocado-docs"
bundle

Add this line to the top of spec/spec_helper.rb:

require 'avocado/rspec'

Avocado will not document specs that are tagged with document: false in the metadata.

Add this line to your test/test_helper.rb:

require 'avocado/minitest'

Add this line to your env.rb:

require 'avocado/cucumber'

Avocado will not document scenarios that are tagged with @nodoc.

You can configure Avocado using the Avocado.configure block, here are the options with defaults (further explanation below):

Avocado.configure do |config|
  config.url = nil
  config.headers = []
  config.upload_id = proc { SecureRandom.uuid }
  config.document_if = proc { |_request, _response| true }
  config.ignored_params = %w(controller action format)
  config.uploader = Avocado::Uploader.instance
  config.storage = Avocado::Storage::File.new ::Rails.root
end

url must be set to a valid URL. Avocado will POST the JSON file to this endpoint. If using the default Avocado::Engine, set it to the mounted engine URL, for example: "my-server.com/avocado" if you mounted the engine at "/avocado".

headers is an array of headers that Avocado should document if they exist (for example, you may want to document the 'Authorization' header). By default, all headers are ignored because the documentation can be very messy.

storage is the strategy used on the server to store the data. By default, the server will store the data in a file. This may have issues with multi-server setups. You can create your own strategy, or check out avocado-redis.

upload_id is an identifier that can tie multiple JSON file uploads to a single test run. This can be useful if you have two different test suites (Cucumber and RSpec for example) or if you are running your tests in parallel. On Jenkins, you can set this to ENV['BUILD_NUMBER']. By default, the value is randomized so multiple uploads are effectively disabled.

document_if is a proc that determines whether or not Avocado will document a spec. This can be useful if you want to set environment variables on CI servers so that only those servers are performing the JSON upload.

ignored_params is a list of params that are ignored during documentation. By default, the 'controller', 'action', and 'format' params that Rails sends with every request are ignored. You can add to this array via <<, or override it entirely with =.

uploader is the object that will perform the upload at the end of the test run. If you need some extremely custom behavior, you can override this if you'd like.

Avocado will automatically attach itself to all JSON requests in the test environment. It does this by monkeypatching ActionController::Base with an around_action. If the response is a blank 204 or JSON parseable, the details will be logged and eventually uploaded as JSON.

Avocado comes with a default documentation viewer you can mount as a Rails engine:

mount Avocado::Engine, at: '/avocado'

It will read the avocado JSON and show a decent looking documentation page.