swagger的使用

rails - swagger的使用 rswag 与 openapi v3

refer to: https://medium.com/@clarkjohnson_85334/adding-swagger-docs-to-a-rails-6-api-using-rswag-a3e8bc577986

rswag 官网: https://github.com/rswag/rswag/

open api v3 官网: https://github.com/OAI/OpenAPI-Specification

如何看文档

看rswag官方文档搞不定，因为rswag这个项目默认大家是熟悉open apiv3 的

open api v3  则需要慢慢的去看

所以应该直接看 最上面的那个例子.

安装

跟rspec绑定在一起的，通过分析rspec的controller的调用，来生成swagger.json / yaml

然后在 /api-docs 页面显示

安装:

rails 6 

ruby 3.0.3 

创建一个新项目

rails new test_swagger

在Gem中增加如下内容

gem 'rswag'
gem 'rswag-api'
gem 'rswag-ui'

group :test do
   gem 'database_cleaner'
   gem 'factory_bot_rails'
   gem 'rspec-rails'
   gem 'rswag-specs'
 end

注意一定要有 rspec这个gem, 因为 rswag的文档是根据rspec的内容生成的. 

bundle install  安装好所有的gem

生成 rspec

rails g rspec:install

再生成 rswag helper: 

rails g rswag   (这个命令来自于 gem 'rswag' )

上面命令没有的话(如果你按照官方文档操作,则肯定没有 )

就运行下面2个命令

rails g rswag:specs:install   生成swagger_helper

rails g rswag:api:install     生成路由中的 /api-docs

rails g rswag:ui:install     同上,只不过这个也由swagger ui 处理.具体为啥一个路由能映射到2个action 我还没细看

随便生成一个controller 的rswag ( 封装了rspec 的rswag测试文件), 内容如下

rails generate rspec:swagger API::V1::Encounters_Controller

内容如下

2026 vim spec/requests/api/v1/encounters_spec.rb
2028 rails rswag:specs:swaggerize
2031 rails s -p 30333