How we use RSpec to automatically generate API documentations

When developing new api endpoints the last thing that the developer usually does is to write the api documentation. If you release new features every day this will quickly become a problem as the manually written documentation often becomes out of sync.

Thanks to Zipmark, Inc - creator of the gem rspec_api_documentation - we could introduce a new process in our pipeline to get documentation online automatically while writing tests. Instead of test driven development we now have a test and documentation driven development workflow (= TDDD, yes we added a new D).

The advantages are clear:

  • Documentation is always in sync with new features and inside the GIT flow
  • You can force developers to write acceptance tests
  • Every endpoint is documented and at the same time tested
  • You don’t need to repeat yourself

Introducing the RSpec API Doc Generator gem

The gem rspec_api_documentation allows you to automatically generate api documentation in various formats like JSON, Markdown, Textile, Text, Api Blueprint and HTML out of RSpec acceptance tests.

You can use the gem in any Ruby project and it’s also possible to use it to test endpoints that are not written in other programming languages.

How to use the gem in Ruby on Rails

Before continuing be sure to setup the rspec-rails gem. After setting up rspec add the rspec_api_documentation gem to the test section of your Gemfile and install it with bundle install.

group :test do
  gem 'rspec-rails'
  gem 'rspec_api_documentation'

To configure the gem you can add a helper acceptance_helper.rb inside the rspec folder and require the rspec docs DSL.

You can define documentation groups as well. A group allows you generate multiple sets of documentation. In our example we have a group for the content deliver api and one for the management api, each with different output paths.

require 'rails_helper'
require 'rspec_api_documentation'
require 'rspec_api_documentation/dsl'

RspecApiDocumentation.configure do |config|
  config.format = [:json]
  config.curl_host = 'http://localhost:3000'
  config.api_name = "App API"

  config.define_group :cdn do |config|
    config.docs_dir = Rails.root.join("public", "assets", "api", "cdn")
    config.filter = :cdn

  config.define_group :management do |config|
    config.docs_dir = Rails.root.join("public", "assets", "api", "management")
    config.filter = :management

Following a RSpec acceptance test which shows a simple example of a get request to one of our endpoints. That’s all the code necessary to generate a documentation like you see at

require 'acceptance_helper'

resource "Tags" do
  header "Accept", "application/json"
  header "Content-Type", "application/json"

  parameter :token, "Private token", :required => true

  let(:token) { 'YOUR_TEST_TOKEN' }

  get "/v1/cdn/tags", :document => :cdn do
    parameter :starts_with, "Starts with slug", :required => false

    let(:starts_with) { 'de' }

    example_request "Get all tags" do
      expect(status).to eq(200)
      resp = JSON.parse(response_body)
      expect(resp['tags'].size).to eq(2)

Generate the documentation

To generate the documentation simply add --format RspecApiDocumentation::ApiFormatter to the rspec command and the gem will test and build the documentation files under the folder you defined in the configuration.

bundle exec rspec spec/acceptance --format RspecApiDocumentation::ApiFormatter

Adding a viewer

Now that you have generated the documentation in JSON you can use a viewer gem like Apitome or provide your own custom view.

In our case we use the generated JSON within Storyblok. We use Sinatra and Shopify’s liquid to render the view and enrich the JSON with custom fields managed in the CMS.

View of Rspec Api documentation


The gem rspec_api_documentation saves a lot of time and is one of the most helpful gems for me. With the structured JSON you can completely customize the presentation layer of your documentation and extend it with your own fields. Thank’s to the guys of Zipmark, Inc for providing this awesome open source project to us!

More to read...

About the author

Alexander Feiglstorfer

Alexander Feiglstorfer

Passionate developer and always in search of the most effective way to resolve a problem. After working 13 years for agencies and SaaS companies using almost every CMS out there he founded Storyblok to solve the problem of being forced to a technology, proprietary template languages and the plugin hell of monolithic systems.