Short answer
If you’re not using Rails, probably nay. Unless you like activesupport being loaded in surprising places.
Long answer
Rspec_api_documentation is a cool way of generating an API documentation straight from your acceptance specs. It takes the example requests and presents the params and API output in a nice little HTML format that you can point your API consumers at and pretend it’s documentation.
So, imagine a speced Sinatra API app that looks like that:
# fancy_sinatra_api.rb
class FancyAPI < API
patch '/:id' do
object = FancyObject.find(params[:id])
object.update(params[:fancy_object]
object.to_json
end
end
# fancy_sinatra_api_spec.rb
resource "FancyObject" do
set_app FancyAPI
before { @object = FancyObject.create(default_params) }
patch '/:id' do
example_request 'Updating the object', id: @object.id do
expect(status).to == 200
expect(JSON.parse(response_body)['my_fancy_field']).to == 'fancy value'
end
end
end
It’s all nice and dandy when you run the specs. The output’s perfect, everything passes, so you put it in production. And it breaks.
The reason the specs passed is that rspec_api_documentation depends on
activesupport, which provides a fancy .to_json method. In production you don’t
load rspec_api_documentation, so you don’t load activesupport, so your .to_json
is much less fancy and instead of creating a hash of the object attributes just
calls a to_s on the object and JSONifies the string it gets. It all results in
your API response looking more like this: **#
What’s the lesson here? Well, a bit of everything:
The less dependencies, the better.
If you’re writing a testing tool, you shouldn’t be loading frontend helpers.
Writing documentation is still difficult.
When in doubt, use object.method(:to_json).source_location to figure out what’s going on.