Rspec API 文档：分离 public 和私有 API 无效

Question

我正在尝试将我的 API 文档与 public 和开发人员文档分开，这样我就可以拥有单独的文档，我可以将这些文档提供给除我之外的其他人。

为此，我正在使用 Rails 和 gem，称为 rspec_api_documentation，但我无法让它工作。 github 页面中提供的配置选项似乎不起作用。

我先尝试自己的项目，然后检查 example application 并在那里进行修改：

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

...

输出：

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

我也尝试删除 developers 组，然后它没有给出错误，但是当我打开生成的 /doc/api/public/index.html 它是一个空文件，上面写着 "Example App API".

感谢任何帮助，谢谢。

Answer 1

将这些添加到 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

然后在示例中这样做：

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

rspec_api_documentation会自动创建目录'private_docs'，您可以打开private_docs/index.html验证生成的文档。

Rspec API 文档：分离 public 和私有 API 无效

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

ruby-on-rails

ruby

rspec

rspec-api-documentation