とにかくRails6でrswagを動かす #Rails

紹介する内容

swagger.jsonから作られたAPIドキュメント画面が見えます（rswag-ui）
rspecで手作りのAPIのテストができます(rspec)
https://github.com/rswag/rswag が紹介する対象です

結論

rails newしたプロジェクトで`とにかく`rswagを動かせる実装とコマンドです

Gemfileにgemを追加してbundle installします

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

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

実行コマンドです

bundle exec rails g rswag:api:install
bundle exec rails g rswag:ui:install

bundle exec rails generate rspec:install

RAILS_ENV=test bundle exec rails g rswag:specs:install
RAILS_ENV=test rake rswag:specs:swaggerize

Gem installとコマンドが問題なく実行されたら以下のイメージが確認できます
ブラウザ上でAPIドキュメントが見えます
APIドキュメントに例を追加した画面は一番下のAPIドキュメント例が追加された画面とrspecを実行してみますで確認できます

APIドキュメント画面の内容は`RAILS_ENV=test rake rswag:specs:swaggerize`で作られたjsonかyamlファイル次第です

spec/swagger_helper.rbでconfig.swagger_docsにAPIドキュメントで見せたい内容を書いて、RAILS_ENV=test rake rswag:specs:swaggerizeしたら、jsonかyamlファイルが作られます
- config.swagger_docs内容次第で、上の緑色のcreateがいるイメージで見える作られたファイルたちを調整が必要があります

APIドキュメントに使うjsonやyamlファイルは`RAILS_ENV=test rake rswag:specs:swaggerize`で作りますが、下準備が必要でした

RAILS_ENV=test bundle exec rails g rswag:specs:installでspec/swagger_helper.rbを作ります
spec/swagger_helper.rbのconfig.swagger_docs部分にAPIドキュメントで見せたい内容を書きます
RAILS_ENV=test rake rswag:specs:swaggerizeを実行すると、spec/swagger_helper.rbのconfig.swagger_docsの通り作ってくれます

筆者はswagger.jsonを手作りして動かしました。READMEを復習した後に自動生成する方法に気づきました。以下はspec/swagger_helper.rbに書かれている内容です

...(省略)
# When you run the 'rswag:specs:swaggerize' rake task, the complete Swagger will
# be generated at the provided relative path under swagger_root
...(省略)

https://github.com/rswag/rswag#getting-started

`RAILS_ENV=test rake rswag:specs:swaggerize`でエラーになったら、`spec/spec_helper.rb`と`spec/rails_helper.rb`があるか確認してください

rails newからrswag入れようとしたら、はまるかもしれません
エラーなるパターン
bundle exec rails generate rspec:installで治ります

紹介始めます

ディレクトリ構成

全体ソースコードは https://github.com/cheekykorkind/qiita-example/tree/master/rails/6/rswag で確認できます。
結論のrails newしたプロジェクトでとにかくrswagを動かせる実装とコマンドですを全部実行した上で、
spec/swagger_helper.rbとinitializers/rswag-ui.rbを修正して、APIドキュメントに例を追加したコードです。

全体図
手動で調整した部分
- spec/swagger_helper.rb
- config/initializers/rswag-ui.rb
手動で作った部分
- spec/api/v1/books_spec.rb
- app/controllers/api/v1/books_controller.rb

app/controllers/api/v1/books_controller.rb実装周り説明

rswagと直接的に関係ないところです。Railsのコントローラーでjsonを返すようにしました

spec/swagger_helper.rb実装周り説明

以下のイメージとソースコード https://github.com/cheekykorkind/qiita-example/blob/master/rails/6/rswag/swagger/v1/swagger.json を参考すると書き方が理解できると思います

initializers/rswag-ui.rb実装周り説明

APIドキュメントに使うファイルをjsonにしたから、yaml部分をjsonに変えました

  # コマンド実行で作られるところ
  # c.swagger_endpoint '/api-docs/v1/swagger.yaml', 'API V1 Docs'

  # jsonファイルを使うから修正
  c.swagger_endpoint '/api-docs/v1/swagger.json', 'API V1 Docs'

APIドキュメント例が追加された画面とrspecを実行してみます

docker composeがあるデレクトリー移動に移動します
- cd qitta-example/rails/6/rswag
dockerコンテナをバックグラウンドで起動します
- DOCKER_UID=$(id -u $USER) DOCKER_GID=$(id -g $USER) docker-compose up -d
rspecでAPIを試します
- RAILS_ENV=test bundle exec rspec
ブラウザでAPIドキュメントを確認します
- http://192.168.33.14:3000/api-docs
  - 開発環境次第でipやportが変わる可能性があります

とにかくRails6でrswagを動かす