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'
end
    

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
  end

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

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 storyblok.com/docs/Delivery-Api/Tags

        
      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)
    end
  end
end
    

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.

<div class="codeblock__title">console</div>

        
      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.

Conclusion

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!