とにかくRails6でrswagを動かす

紹介する内容

• 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で作りますが、下準備が必要でした

1. RAILS_ENV=test bundle exec rails g rswag:specs:installでspec/swagger_helper.rbを作ります
2. spec/swagger_helper.rbのconfig.swagger_docs部分にAPIドキュメントで見せたい内容を書きます
3. 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を実行してみます

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