Question

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

为此，我使用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时，它是一个空文件，说“示例应用程序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将自动创建目录＆＃39; private_docs＆＃39;并且您可以打开private_docs / index.html来验证生成的文档。

Rspec API文档：分离公共和私有API不起作用

1 个答案: