OpenAPI? What Is That? Is That Tasty?

Transcript

1. OpenAPI？ なにそれ？ おいしいの？ 2021/10/29 えにしテック永和技術交流会 @cafedomancer
2. Shohei Umemoto @cafedomancer えにしテックでプログラマをや っています。2015年10月に新 卒入社したのでちょうど7年目 になります。さいきんの趣味は ヤマノススメの影響ではじめた 登山です。もうすぐ30歳になる ので記念に富士山にのぼってみ たい！
3. Pocco
5. Poccoについて 北海道産の食材を使用したアイスを定期便としてお届けするサービスです。コロッケ さん(corock.co)が運営するサービスで、えにしテックが技術支援する形で進めてい ます。もともとはShopifyで販売を行っていたのですが、モバイルアプリとしてサー ビスを提供することになり、2020年10月ごろから新規プロジェクトとして開発をス タートしました。フロントエンドはFlutter、バックエンドはRailsで作られており、 REST APIを介してやり取りする形になっています。開発もそれぞれのチームに分か れて行っています。えにしテックでは主にバックエンドのRailsを中心として開発を 行っています。
7. REST API
8. えにしテック コロッケさん 業務委託の方 (北海道) (北海道) (東京・大阪)
9. OpenAPIをやることになったキッカケ Flutterチームの方が「REST API の仕様をドキュメントとして記述してほしい。 OpenAPIかなにかで書いてもらえると助かる。」とおっしゃられました。しかしその 当時ぼくはOpenAPIについてよく知らなかったので、とりあえず「わかりました！こ ちらで方法を検討してみます！」とお返事しました。それがキッカケでOpenAPIを用 いた開発のやり方を調べ始めることになりました。正直なところOpenAPIで仕様を書 くなんてやったことないしめんどくさそうと当初は思っていたのですが、やってみた ら結構よかったので、今日はそのことについてお話ししていこうと思います。
10. えにしテック 業務委託の方 OpenAPI か な に かでREST APIの 仕様を書いても らえると助かる のですが... わかりました！ こちらでやり方 を考えてみます ね！ (OpenAPIとかや ったことないし なんかめんどく さそう...)
12. OpenAPI
13. OpenAPIについて REST APIの仕様をYAMLまたはJSONで記述するためのフォーマットです。パス・ HTTPメソッド・ステータスコード・Content-Type・リクエスト・レスポンスなど を仕様として記述することができます。Swagger EditorやSwagger UI、Swagger Codegenといったツール群と合わせて使用します。実際に見てみたほうが分かりやす いと思うので、Swagger EditorとSwagger UIについてデモを行います。Swagger CodegenについてはPoccoのプロジェクトでは使用していないので、今日の発表でも 扱わないことにします。cafedomancer/petstoreにOpenAPIで記述した仕様を載せ ているので、全体を見てみたい方はそちらをのぞいてみてください。
16. RailsとOpenAPIを組み合わせてつかう committee(committee-rails)というgemを使うことで、リクエストとレスポンスが OpeAPIで記述した仕様にしたがっているかを、request specまたはintegration testでチェックすることができます。実際にどのように使用するのかをデモを行いな がら説明します。cafedomancer/petstoreにコードを掲載しているので、細かい部 分も見てみたい方はそちらをのぞいてみてください。
19. やりかた
20. どのようなAPIが必要になる かを全員で議論してAPIの仕 様を定めていきます。仕様が 定まったらOpenAPIで仕様 を記述していきます。 仕様フェーズで定めた仕様を ベ ー ス に Flutter チ ー ム と Railsチームが並行してそれ ぞれ開発作業を進めていきま す。 実装フェーズで作成したもの をstaging環境にデプロイし て動作確認を行います。問題 なければproduction環境に デプロイしてリリースを完了 します。 ①仕様フェーズ ②実装フェーズ ③連携フェーズ 普段の開発の進め方 最近つくった退会機能を例にして進め方を紹介しようと思います(ほんとは退会して ほしくないけどいつでも退会できるようにはしたいのでつくりました🥲)。
21. pocco-openapi pocco-flutter pocco-rails
22. ①仕様フェーズ どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら 仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ ればこの段階で仕様の調整を追加で行います。pull requestがapproveされてmainに mergeされたらこのフェーズは完了になります。
23. ①仕様フェーズ どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら 仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ ればこの段階で仕様の調整を追加で行います。pull requestがapproveされてmainに mergeされたらこのフェーズは完了になります。
25. ①仕様フェーズ どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら 仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ ればこの段階で仕様の調整を追加で行います。pull requestがapproveされてmainに mergeされたらこのフェーズは完了になります。
28. ①仕様フェーズ どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら 仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ ればこの段階で仕様の調整を追加で行います。pull requestがapproveされてmainに mergeされたらこのフェーズは完了になります。
31. ①仕様フェーズ どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら 仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ ればこの段階で仕様の調整を追加で行います。pull requestがapproveされてmainに mergeされたらこのフェーズは完了になります。
33. ②実装フェーズ Flutterチーム側はRapidoc(Swagger UIの 代替ツール)でAPIの仕様を確認しながら実 装を進めていきます。Railsチーム側は committeeを使って仕様を満たしている ことを確認しながらAPIの開発を進めてい きます。 WEB+DB-PRESS-Vol.108より引用
36. ③連携フェーズ APIの開発作業が完了したら、Railsチーム側ではstaging環境に変更をデプロイし、 RailsチームからFlutterチームにその旨を連絡します。Flutterチーム側ではAPIサー バーとしてstaging環境を指定したアプリで動作確認を行います。動作確認で問題が なければRailsチーム側ではproduction環境に変更をデプロイし、Flutterチーム側で はApp Store/Google Playへの申請/公開を行います。これでリリースの完了です。
38. 進め方のおさらい どのようなAPIが必要になる かを全員で議論してAPIの仕 様を定めていきます。仕様が 定まったらOpenAPIで仕様 を記述していきます。 仕様フェーズで定めた仕様を ベ ー ス に Flutter チ ー ム と Railsチームが並行してそれ ぞれ開発作業を進めていきま す。 実装フェーズで作成したもの をstaging環境にデプロイし て動作確認を行います。問題 なければproduction環境に デプロイしてリリースを完了 します。 ①仕様フェーズ ②実装フェーズ ③連携フェーズ このやり方はWEB+DB-PRESS-Vol.108を参考にしているのでもし興味がある方はそ ちらをぜひ読んでみてください。
39. どうなの
40. 仕様を記述するのは意外とカンタン OpenAPIのフォーマットがシンプルなので仕様を記述するのはそれほど大変ではあり ませんでした。YAMLを書くだけて見やすいドキュメント一式が手に入るので仕様を 記述するコストも十分ペイすると考えられます。一方でリクエストやレスポンスで複 雑な形式のJSONをやり取りするケースでは、OpenAPIでJSONのフォーマットを記 述するのもその分だけ大変になります。PoccoではJSON:API(jsonapi.org)をフォー マットとして採用していたのでこの点がなかなか大変でした。OpenAPIにはスキーマ を再利用するためのcomponentsと呼ばれる仕組みがあるので、それを利用すること である程度はこの問題を緩和できているのではないかと思います。
41. 仕様と実装の乖離が起こりにくくなる 仕様→実装の順に進めている限りは、実装が仕様に基づいていることはcommitteeに よって担保されるので、仕様と実装とが乖離するということは無くなります。普段の 開発でも「ドキュメントと書いてあるのと違うんだけど...」といったことは一度もあ りませんでした。
42. 仕様を中心にコラボレーションできる OpenAPIはYAMLで書かれたただのファイルなので、ソースコードと同じように GitHub上で管理することができます。GitHub上で管理するようにすれば、普段の開 発でやっているのと同じように、仕様の策定においてもコラボレーションすることが できます。今回は初めて一緒に仕事をするチームで、ぼくにとっては初めてのモバイ ルアプリ向けのAPI開発でしたが、GitHubフローに乗せられたおかげでFlutterチー ムとRailsチームが協力してAPIの仕様を考えることができました。いろいろ初めてだ けどうまくいったのは、この点が大きく寄与しているのかなと思います。
43. 参考文献
44. https://booth.pm/ja/items/1571902 https://gihyo.jp/magazine/wdpress/archive/2019/vol108