You may have docs for your API, but do you have an API for your docs? With RspecApiDocumentation and Raddocs, you can cURL for your documentation. SmartLogic's Eric Oestrich tells you how. Check out the slides, or read about it here: http://blog.smartlogicsolutions.com/2012/07/12/curlin-for-docs/

1. cURLin' for Docs
Eric Oestrich
@ericoestrich
oestri.ch

2. Say what?
$ curl -H "Accept: text/docs+plain"
http://rad-example.herokuapp.com/orders

3. Example
Getting a list of orders
------------------------
Parameters:
* page - Current page of orders

4. Request
Request:
GET /orders?page=1
Accept: application/json
Content-Type: application/json
Cookie:
Host: example.org
page=1

5. Response
Response:
Status: 200 OK
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 121
Content-Type: application/json; charset=utf-8
ETag: "6cd5831e98b0090b64672b5604d9eb2a"
X-Runtime: 0.019010
X-UA-Compatible: IE=Edge,chrome=1
[{"email":"email0@example.com","name":"Order 0","paid":
true},{"email":"email1@example.com","name":"Order 1","
paid":true}]

6. Neat-o, how do I get that?

7. Install some gems
Gemfile
group :test do
gem 'rspec_api_documentation'
gem 'raddocs'
end

8. Write RAD tests
spec/acceptance/orders_spec.rb
resource "Orders" do
get "/orders" do
it "should ..." do
...
end
end
end

9. Configure the output formats
spec/spec_helper.rb
RspecApiDocumentation.configure do |config|
config.formats = [:json, :combined_text]
end

10. Generate docs
$ rake docs:generate

11. Mount Raddocs
config/routes.rb
Application.routes.draw do
resources :orders
match "/docs" => Raddocs::App,
:anchor => false
end

12. Use Raddocs::Middleware
config/application.rb
module Example
class Application < Rails::Application
...
config.middleware.use "Raddocs::Middleware"
...
end
end

13. cURL Away
$ curl -H "Accept: text/docs+plain"
http://localhost/orders

14. Demo

15. Gems
● rspec_api_documentation
○ http://github.com/zipmark/rspec_api_documentation
● raddocs
○ http://github.com/oestrich/raddocs

16. Questions?