How we use RSpec to automatically generate API documentations

    Try Storyblok

    Storyblok is the first headless CMS that works for developers & marketers alike.

    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!