AFTER RubyKaigi 2019でOpenAPI 3とcommitteeの発表をしました

2019-05-16

AFTER RubyKaigi 2019で、『Q&A for “how to use OpenAPI3 for API developer”』を発表しました。　

資料はこちら

ベンチマークのコードはこちらになります。
https://gist.github.com/ota42y/1a5fb27e31aa5868af307fd66f52878b

ベンチマークは登壇直後のブログで書いたのよりより誤差が少ない方法にしたため、こちらのほうがより正確で、やはり気にするほどの影響はなさそうです。

ちょうどGW前に軽く書いて、きちんと作ってどこかで発表するかなーと思っていたところにちょうどいいタイミングであったので助かりました。

committeeのベンチマークをちゃんと取ったけど、どこかrubykaigi振り返りで発表枠ある所あるかな…ちこくkaigは予定かぶってた(´・_・`)
— おおた@RubyKaigi登壇done (@ota42y) 2019年4月25日

懇親会でのQ&A

また、会期中のQ&Aを話したら懇親会で更に質問が来たので書いておきます。

レスポンスのバリデーションを本番で使ってないのはなぜか

マスターデータの投入ミスなどでたまに異常なレスポンスになった場合に、サーバ側でのレスポンスバリデーションでエラーにすると確実にエラーになりますが、クライアント側の実装によっては偶然動いてくれる可能性もあります。そのため、サーバで止めるよりクライアントに渡してどうしてもダメならエラーにするほうが、ユーザ体験の期待値的には高いので使っていません。また、古いAPIなどはドキュメントがなくて例外ケースをおいきれず、定義がきちんと作れていないという現状もあります。

ただし、今WIPでPRにしてるやつを入れると、バリデーションエラーの際にログだけ吐いて正常に返すことができるので、これが入ると本番でおかしい状態を安全に検知できるので、本番に入れるのはありかなと思います。(検証してないだけなので、あとで検証して問題なければ入れます)
add ignore_error option

コードからOpenAPIを生成するのと、直接YAMLを書くのはどちらがいいか

grapeやfastapiのように、フレームワークが実装からOpenAPIの定義を出力してくれるものがあります。こちらの方式は実装と定義を同時に書ける、実装と定義が常に揃うという利点があり、直接YAMLを書くのとどちらがいいのかという話です。これに関してはどちらかが明確に優れていることは無いと思います。

grapeのように実装と同時に定義を掛けるというのは大きな利点です。ですが一方でgrapeにロックインされる問題や、実装ミスがそのまま定義のミスに繋がる、非Rubyエンジニアが参入できないといったマイナス面も存在します。そのためどちらが優れているということはなく、例えばすでにgrapeを使っているのであれば自動生成して良いと思いますし、一方で自動生成のためだけにgrapeを導入するというのは危ないのではないかと思います。

あくまでも開発をサポートするためのOpenAPIなので、チームにあった形で取り入れていけばいいかなと思います。 (話してて、こういったチームに合わせた方法で自由に取り入れられる点は、ほとんど決まっているGraphQLやgRPCとの大きな違いかなーと思いました。もちろん後者には全部入りなので迷いにくいという利点がありますが)