Building APIs with Rails: Documentation Testing

Now that we’ve started building a very basic API, we should make sure that the documentation is kept up to date with our progress. Even better, we can use our documentation as a basic contract test, to make sure we aren’t lying about what our API offers.

I’ve written tutorials in the past about how Dredd works, so this video will just go over this stuff in a bit more detail.

Source Code

Notes

You can easily install dredd using npm:

npm install -g dredd

Once installed, you can use its init function to set things up:

dredd init

With the correct values added, running dredd is a single command. The output can be a little verbose, so I like to pipe it to a log file:

dredd > log/dredd.log

For dredd to work, there needs to be data in the database. If you make a request to /products/1 and there is no record with ID=1 in the database, then it will return a 404 response, instead of a 200 response with all the expected attributes.

To solve this we can use database seeding. A lot of apps use seeding for other things, so it can be really useful to make a custom seed out of the way of anything else:

# lib/tasks/custom_seeds.rake
namespace :db do
  namespace :seed do
    Dir[File.join(Rails.root, 'db', 'seeds', '*.rb')].each do |filename|
      task_name = File.basename(filename, '.rb').intern
      task task_name => :environment do
        load(filename) if File.exist?(filename)
      end
    end
  end
end

Now, we can populate the seeds with really basic record creation. In fact, this is the same stuff we used in episode 3:

# db/seeds/dredd.rb

manufacturer = Manufacturer.create(name: "Thatchers", about: "Pretty solid cider makers who are randomly moving their factories in the south west and going to Ireland...", city: "Dublin", country: "Ireland")

Product.create(manufacturer: manufacturer, name: 'Katies', description: "Unnecessarily strong fizzy cider that sells for the same price as normal ciders.", apv: 7.6, product_type: 'cider')

Product.create(manufacturer: manufacturer, name: 'Thatchers Dry', description: "As the name suggests this is dry, and a little tangy.", apv: 6.5, product_type: 'cider')

To check that works, you can run it with the following command:

rake db:seed:dredd

In isolation, that is not very helpful. We also don’t want to mess with our development database. Using the entire following command, you can use the testing database, create a fresh DB every time, load the schema up, then run dredd.

RAILS_ENV=test rake db:drop db:create db:migrate db:seed:dredd && dredd

This would be a fairly annoying command to have to remember, wrap it up in a simple Makefile:

# Makefile
.PHONY: docs_test
docs_test:
		@echo "Seeding database for documentation testing"
		@RAILS_ENV=test rake db:drop db:create db:migrate db:seed:dredd
		@echo "Running dredd... check logs/dredd.log for more information"
		@RAILS_ENV=test dredd > log/dredd.log && echo "Documentation is all good!"

With that Makefile in your project root, you can simply run this:

$ make docs_test

We’ll be making a few more make commands over the next few videos. They’re really useful!

Interested in a Proper Series?

These rough videos will be replaced with a nicely recorded series, and to get updates about that, just let me know your email address.