Question

我在Google上做了一些搜索，以找到一种适当且易于实现的方式来为现有的Rails API应用生成Swagger文档。简而言之，有两种实现方式：通过控制器，模型或通过Rspec控制器/请求规范。列表不太长，选择也不容易：

swagger-docs宝石-最古老的宝石。优点：实施将在控制器中完成。缺点：不支持Swagger V2 版本并且仅限于 1.2 。
swagger-blocks gem-swagger-docs的改进版本，支持Swagger V2版本，实现将在控制器，模型中完成。但是我无法使其工作，Swagger Editor无法解析生成的json文件。
rswag gem：使用基于Swagger的DSL扩展rspec-rails“请求规范”。就个人而言，我发现很难在现有的Rails应用中实现该应用有两个原因：
- 您将不得不修改现有的请求规范
- 请求规范看起来真的很奇怪，语法也不是 RSpec -ish。
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

运行“捆绑安装”
运行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
导航至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进行验证。

希望这会有所帮助。

Answer 2

我们的工作解决方案是使用：

swagger-blocks gem以生成Swagger JSON
Swagger UI Console Chrome Extension提供Swagger UI

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

2 个答案: