You may have docs for your API, but do you have an API for your docs? With RspecApiDocumentation and Raddocs, you can cURL for your documentation. Try out the following cURL command to see for yourself:
$ curl -H "Accept: text/docs+plain" http://rad-example.herokuapp.com/orders
- Install the gem
- Write tests
- Host via public or Raddocs
What is the rspec_api_documentation gem?
The rspec_api_documentation gem (RAD for short) is a gem that lets you easily create documentation for your API based on tests for the API. You write acceptance tests and it will output docs.
- rspec is installed and setup
Installing the gem
Installing RAD is as simple as adding it to your Gemfile. You might want to add it to a test and development group because it has a handy rake task for generating docs.
Once RAD is installed there are several options you probably want to configure. Listed below are all of the default options that RAD ships with. The most common ones you will want to change are “api_name”, “docs_dir”, “format”, and “url_prefix”.
RspecApiDocumentation.configure do |config| # All settings shown are the default values config.app = Rails.application # if it’s a rails app config.api_name = “API Documentation” config.docs_dir = Rails.root.join(“docs”) config.format = :html # also: :json, :wurl, :combined_text, :combined_json config.url_prefix = “” # If you want cURL commands to be included in your docs, # set to not nil config.curl_host = nil # “http://myapp.example.com” # Filtering # If you set the :document key on an example to a particular group # you can only output those examples config.filter = :all # You can also exclude by keys config.exclusion_filter = nil # To use your own templates config.template_path = “” # The default template path is inside of RAD # Instead of sorting alphabetically, keep the order in the spec file config.keep_source_order = false config.define_group :public do |config| # When you define a sub group these defaults are set # Along with all of the parents settings config.docs_dir = Rails.root.join(“docs”, “public”) config.filter = :public config.url_prefix = “/public” end end
Tests for RAD are written in a DSL which helps assist in getting the metadata correct for properly formatting the outputted docs. Tests go in
DSL Methods of Interest
Host via public or Raddocs
This is the easiest method. If you generate HTML or wURL HTML output then you can simply place the generated docs inside of the publicly accessible folder in your application when you deploy.
Raddocs is a simple Sinatra app that will take the JSON output from RAD and serve it up as HTML pages. The output is very similar to the HTML generated pages, but Raddocs allows us to have better asset handling than straight HTML.
- Generate :json and :combined_text output from RAD
- Configure Raddocs
- Mount Raddocs
RspecApiDocumentation.configure do |config| config.formats = [:json, :combined_text] end
Raddocs.configure do |config| # output dir from RAD config.docs_dir = “docs” # Should be in the form of text/vnd.com.example.docs+plain config.docs_mime_type = /text\/docs\+plain/ end
match “/docs” => Raddocs::App, :anchor => false
You now have docs that won’t generate if your tests fail, making sure that they are correct. And you can view them in a console as well as the browser.
Check out our other aricles on API and keeping your team organized: