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

Question

我用谷歌搜索了一下，找到了一种适当且易于实现的方法来为现有的 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：通过请求规范实现。和上面一样的缺点。

有人知道其他 gems 可以为现有的 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

• 运行“捆绑安装”
• 运行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 服务器rails s
• 导航至localhost:3000/api-docs查看生成的 Swagger 文档。

注意：它工作得很好并且满足了客户的要求，即：

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

我rswag-specs从中删除了 gem，Gemfile因为它无法验证我在 Rails API 应用程序中使用的active_model_serializers gem以JSON API 格式返回的响应模式。我总是必须：

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

现在，请求规范可以同时由 RSpec 和 rspec-rails-swagger 进行验证，无需麻烦。

希望这可以帮助。