Rspec API Documentation: Separating public and private APIs is not working

Question

I am trying to separate my API docs to public and developers documentation, so that I can have separate docs which I can give to people other than me.

For this I am using Rails and gem known as rspec_api_documentation, however I can't get it to work. It seems that provided configuration options within the github page doesn't work.

I tried first with my own project and then by checking out example application and making the modifications there:

acceptance_helper.rb:

...

# Only document examples marked as 'public'
config.define_group :public do |config|
  config.filter = :public
end

# Only document examples marked as 'developers'
config.define_group :developers do |config|
  config.filter = :developers
end

...

orders_spec.rb:

...

example_request "Updating an order", :document => :public do

...

example_request "Deleting an order", :document => :developers do

...

Output:

Maunos-MacBook-Pro:example maunovaha$ rake docs:generate
/Users/maunovaha/.rvm/rubies/ruby-2.1.3/bin/ruby -I/Users/maunovaha/.rvm/gems/ruby-2.1.3/gems/rspec-core-3.0.1/lib:/Users/maunovaha/.rvm/gems/ruby-2.1.3/gems/rspec-support-3.0.0/lib -S /Users/maunovaha/.rvm/gems/ruby-2.1.3/gems/rspec-core-3.0.1/exe/rspec spec/acceptance/orders_spec.rb --format RspecApiDocumentation::ApiFormatter
Generating API Docs
Run options: include {:focus=>true}

All examples were filtered out; ignoring {:focus=>true}
  Orders
  PUT /orders/:id
    * Updating an order
  POST /orders
    * Creating an order
  DELETE /orders/:id
    ! Deleting an order (FAILED)
  GET /orders
    * Getting a list of orders
  HEAD /orders
    * Getting the headers
  GET /orders/:id
    * Getting a specific order

Failures:

  1) Orders DELETE /orders/:id Deleting an order
     Failure/Error: Unable to find matching line from backtrace
     ActionDispatch::ParamsParser::ParseError:
       795: unexpected token at 'document=developers'
     # /Users/maunovaha/Documents/repos/rspec_api_documentation/lib/rspec_api_documentation/rack_test_client.rb:38:in `do_request'
     # /Users/maunovaha/Documents/repos/rspec_api_documentation/lib/rspec_api_documentation/client_base.rb:42:in `process'
     # /Users/maunovaha/Documents/repos/rspec_api_documentation/lib/rspec_api_documentation/client_base.rb:24:in `delete'

Finished in 0.06349 seconds (files took 0.8706 seconds to load)
6 examples, 1 failure

Failed examples:

rspec ./spec/acceptance/orders_spec.rb:90 # Orders DELETE /orders/:id Deleting an order

Top 6 slowest examples (0.05349 seconds, 84.2% of total time):
  Orders PUT /orders/:id Updating an order
    0.02879 seconds ./spec/acceptance/orders_spec.rb:82
  Orders POST /orders Creating an order
    0.00884 seconds ./spec/acceptance/orders_spec.rb:47
  Orders GET /orders Getting a list of orders
    0.0061 seconds ./spec/acceptance/orders_spec.rb:20
  Orders GET /orders/:id Getting a specific order
    0.00498 seconds ./spec/acceptance/orders_spec.rb:66
  Orders HEAD /orders Getting the headers
    0.00273 seconds ./spec/acceptance/orders_spec.rb:27
  Orders DELETE /orders/:id Deleting an order
    0.00205 seconds ./spec/acceptance/orders_spec.rb:90

Randomized with seed 47568

I also tried to remove developers group, and it then gives no error but when I open up generated /doc/api/public/index.html it's an empty file saying "Example App API".

Any help appreciated, thanks.

Answer 1

Add these to the acceptance_helper.rb.

RspecApiDocumentation.configure do |config|

  config.format = [:json, :combined_text, :html]

  config.define_group :public do |config|
    config.api_name = "My Api"
    config.docs_dir = Rails.root.join('docs', "")
  end

  config.define_group :private do |config|
    config.api_name = "My private API"
    config.docs_dir = Rails.root.join('private_docs', "")
  end

Then in the examples do this:

  get "/order/status", :document => :public do

rspec_api_documentation will automatically create the directory 'private_docs' and you can open private_docs/index.html to verify the generated docs.