とにかく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とコマンドが問題なく実行されたら以下のイメージが確認できます
![allGreen.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/247584/4f4dff13-8b50-ed8c-b785-2aedf8ba8c5c.png)

- ブラウザ上でAPIドキュメントが見えます
![justAPIdocument.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/247584/8f8ba7df-96ab-444a-df6a-f86623edbf83.png)


- 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入れようとしたら、はまるかもしれません
- エラーなるパターン
![rakeSwaggerizeError.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/247584/135e7319-73af-e0bf-9203-730fd7afff15.gif)

- `bundle exec rails generate rspec:install`で治ります
![swaggerrizeOk.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/247584/efb7d3fd-1bb7-9846-d2d9-2b1e0c604bd2.png)



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


- 全体図
![allD.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/247584/f8695f6a-593b-f255-90f4-bf5d47ef2a76.png)

- 手動で調整した部分
   - `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 を参考すると書き方が理解できると思います
![bookIndex.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/247584/64ae631b-e95a-d34f-a61c-eb3eceb5fc46.png)



### 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が変わる可能性があります

![showAll.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/247584/f5d2fd1f-0e2b-f3db-3a8d-c9f28dd60f16.gif)