1

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

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

我首先尝试了自己的项目，然后检查了示例应用程序并在那里进行了修改：

验收助手.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

...

订单规格.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”。

任何帮助表示赞赏，谢谢。

4

1 回答 1

2

将这些添加到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 来验证生成的文档。

于 2015-03-25T09:03:12.963 回答