[Rails] OpenAPI (swagger) で書いたAPIドキュメントをテストする。 #Rails

この記事について

OpenAPI (swagger) がかなりイケてるという情報を得て、導入・テストするまでにいろいろ模索したので、その備忘録として書き留めておきます。
「これからRailsプロジェクトにOpenAPIを導入したい！」と思っている方の参考に、少しでもなればなと思います。

また、僕なりにググって、「これがいいんじゃないかなぁ」と思ったものなので
「こっちのほうがいいよ！」ってのがあれば、ぜひ教えてください。。

OpenAPIの記法については、割愛します。ググれば山のようにあるので。。

構成

サーバー：Rails（with docker）
APIドキュメント：OpenAPI
テスト：RSpec + committee (committee-rails)

OpenAPIを導入する

導入といっても、やることは大してありません。
docker hubに、公式イメージでswagger-uiがあるので、それを使います。（参照）

swagger:
    image: swaggerapi/swagger-ui
    volumes:
      - './open_api/open_api.yml:/usr/share/nginx/html/open_api.yml'
    environment:
      API_URL: open_api.yml
    ports:
      - '8080:8080'

volumesの./open_api/open_api.ymlのところに、APIドキュメントが書かかれているファイルまでのパスを指定してください。
environmentのAPI_URLの部分は、ファイル名で大丈夫です。

これで終わりです！ localhost:8080にアクセスすれば、おしゃれなSwagger UIが表示されているかと思います。

他のコンテナで8080使ってるんだよなって方がいたら、ホスト側のポート（host_port:container_port）を9000など、任意のポートを振ってあげてください。

テストできるように設定する

「実際のレスポンスとドキュメントが違う！（おこ）」ってフロントエンド様を怒らせてしまった方いるんじゃないでしょうか。
かといって人力でチェックするのも限界があると思うので、自動でテストできたら楽ですよね！
RSpecでドキュメントも一緒にテストできるように設定していきます。

gem 'committee'  
gem 'committee-rails'

まずは、上二つをインストールしてください。（committee / committee-rails）

rails_helper.rb

require 'spec_helper'
require 'openapi_parser'
require 'committee'
require 'committee/rails/test/methods'

# (中略)

include Committee::Rails::Test::Methods

RSpec.configure do |config|
  # （略）

  # configurations for open api
  open_api = OpenAPIParser.parse(YAML.load_file("#{Rails.root}/open_api/open_api.yml"))
  schema = Committee::Drivers::OpenAPI3::Driver.new.parse(open_api)
  config.add_setting :committee_options
  config.committee_options = { schema: schema }
end

次に、OpenAPIでかかれたymlは、ちょっと独特の記法がはいっているので、パースする必要があります。その処理が上のものです。
config.committee_options = { schema: schema }で、パースしたschemaをテストで使ってくれと指定。

以上で設定は終了です！

実際にテストする

sample_spec.rb

it 'APIドキュメントとレスポンスが一致すること' do
  get '/sample_api'
  assert_response_schema_confirm
end

assert_response_schema_confirmこの1行で、書かれたドキュメントとレスポンスが一致してるかテストしてくれます！

期待したプロパティ以外のものが返ってきてるのに、テストが通ってしまう（{ "hoge": 123 }を期待して、{ "hoge": "123", "foo": "oof"}が返ってきたのにテストが通ってしまう）場合は、ドキュメントを記載しているymlファイルの方に、additionalProperties: falseを加えてやれば大丈夫です！

最後に

冒頭にも書きましたが、「これがよかろう！」と個人的に思ったものなので、他にいいやり方など、ご存知の方がいましたら是非教えてください。
拙い記事で読みづらかったかもしれませんが、読んでくださり、ありがとうございました！