How we use RSpec to automatically generate API documentations
Storyblok is the first headless CMS that works for developers & marketers alike.
On May 13th, 2024, Storyblok started gradually rolling out a new design for its Visual Editor. Therefore, the Visual Editor product screenshots depicted in this resource may not match what you encounter in the Storyblok App. For more information and a detailed reference, please consult this FAQ on the new Visual Editor design.
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
Section titled 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.
Section titled 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
Section titled 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
Section titled 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.
Section titled 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!