用于Rails API应用程序的Swagger文档工具

Question

我google了一下，找到了一个适当且易于实现的方法来为现有的Rails API应用程序生成Swagger文档。简而言之，有两种实现方式：通过控制器，模型或通过Rspec控制器/请求规范。列表不会太长，选择也不容易：

1. swagger-docs gem， - 最古老的宝石。优点：实施将在控制器中完成。缺点：不支持Swagger V2版本，仅限于1.2。
2. swagger-blocks gem， - 改进版的swagger-docs，支持Swagger V2版本，实现是在控制器，模型中完成的。但我无法使其工作，Swagger Editor无法解析生成的json文件。
3. rswag gem：使用基于Swagger的DSL扩展rspec-rails“请求规范”。就个人而言，我发现在现有的Rails应用程序中实现起来非常困难有两个原因： 您将不得不修改现有的请求规范 请求规格看起来很奇怪，语法不是RSpec-ish。
4. rspec-rails-swagger gem：通过请求规范实现。与上述相同的缺点。

有没有人知道其他宝石为现有的Rails API应用程序生成Swagger文档？欢迎任何建议！谢谢。

Answer 1

我得到的解决方案是使用rswag gem和rspec-rails-swagger gem - 通过在Gemfile中添加以下内容来安装rswag gem：

#Gemfile
gem 'rswag-api'
gem 'rswag-ui'

group :development, :test do
  gem 'rspec-rails',         '~> 3.8.1'
  gem 'rspec-rails-swagger', '~> 0.1.5'
...
end

• 运行`bundle install``
• 运行rails g rswag:install生成swagger_helper.rb
• 使用rspec-rails-swagger创建一个新的请求规范，运行rails generate rspec:swagger PostsController（将名称改为你想要编写规范的你想要的控制器）。
• 写一些规格，如rspec-rails-swagger README中所述
• 运行bundle exec rake swagger生成一个swagger.json文件。
• 通过在routes.rb文件中添加以下行来安装RSwag API和RSwag UI引擎：

#../config/routes.rb

Rails.application.routes.draw do
  mount Rswag::Ui::Engine => '/api-docs'
  mount Rswag::Api::Engine => '/api-docs'
...#other routes come here
end

• 用rails s启动你的rails服务器
• 导航到localhost:3000/api-docs以查看生成的Swagger文档。

注意：它工作得很好，并回复客户要求，即：

• 生成Swagger 2.0兼容文档
• 能够直接从Swagger接口执行请求以查看实际数据

我从rswag-specs中删除了Gemfile gem，因为它无法验证我在我的Rails API应用程序中使用的JSON API format gem在active_model_serializers中返回的响应模式。我一直都是这样的：

• 生成文档
• 评论失败的测试
• 然后取消注释失败的测试，以防我需要生成一些新的文档，这真的很难维护。

现在请求规范由RSpec和rspec-rails-swagger同时验证，没有麻烦。

希望这可以帮助。