OpenAPI? What Is That? Is That Tasty?

Transcript

1. OpenAPI？
   なにそれ？
   おいしいの？
   2021/10/29
   えにしテック永和技術交流会
   @cafedomancer
   

   View Slide

2. Shohei Umemoto
   @cafedomancer
   えにしテックでプログラマをや
   っています。2015年10月に新
   卒入社したのでちょうど7年目
   になります。さいきんの趣味は
   ヤマノススメの影響ではじめた
   登山です。もうすぐ30歳になる
   ので記念に富士山にのぼってみ
   たい！
   

   View Slide

3. Pocco
   

   View Slide

4. View Slide

5. Poccoについて
   北海道産の食材を使用したアイスを定期便としてお届けするサービスです。コロッケ
   さん(corock.co)が運営するサービスで、えにしテックが技術支援する形で進めてい
   ます。もともとはShopifyで販売を行っていたのですが、モバイルアプリとしてサー
   ビスを提供することになり、2020年10月ごろから新規プロジェクトとして開発をス
   タートしました。フロントエンドはFlutter、バックエンドはRailsで作られており、
   REST APIを介してやり取りする形になっています。開発もそれぞれのチームに分か
   れて行っています。えにしテックでは主にバックエンドのRailsを中心として開発を
   行っています。
   

   View Slide

6. View Slide

7. REST API
   

   View Slide

8. えにしテック
   コロッケさん
   業務委託の方
   (北海道)
   (北海道)
   (東京・大阪)
   

   View Slide

9. OpenAPIをやることになったキッカケ
   Flutterチームの方が「REST API の仕様をドキュメントとして記述してほしい。
   OpenAPIかなにかで書いてもらえると助かる。」とおっしゃられました。しかしその
   当時ぼくはOpenAPIについてよく知らなかったので、とりあえず「わかりました！こ
   ちらで方法を検討してみます！」とお返事しました。それがキッカケでOpenAPIを用
   いた開発のやり方を調べ始めることになりました。正直なところOpenAPIで仕様を書
   くなんてやったことないしめんどくさそうと当初は思っていたのですが、やってみた
   ら結構よかったので、今日はそのことについてお話ししていこうと思います。
   

   View Slide

10. えにしテック
    業務委託の方
    OpenAPI か な に
    かでREST APIの
    仕様を書いても
    らえると助かる
    のですが...
    わかりました！
    こちらでやり方
    を考えてみます
    ね！
    (OpenAPIとかや
    ったことないし
    なんかめんどく
    さそう...)
    

    View Slide

11. View Slide

12. OpenAPI
    

    View Slide

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で記述した仕様を載せ
    ているので、全体を見てみたい方はそちらをのぞいてみてください。
    

    View Slide

14. View Slide

15. View Slide

16. RailsとOpenAPIを組み合わせてつかう
    committee(committee-rails)というgemを使うことで、リクエストとレスポンスが
    OpeAPIで記述した仕様にしたがっているかを、request specまたはintegration
    testでチェックすることができます。実際にどのように使用するのかをデモを行いな
    がら説明します。cafedomancer/petstoreにコードを掲載しているので、細かい部
    分も見てみたい方はそちらをのぞいてみてください。
    

    View Slide

17. View Slide

18. View Slide

19. やりかた
    

    View Slide

20. どのようなAPIが必要になる
    かを全員で議論してAPIの仕
    様を定めていきます。仕様が
    定まったらOpenAPIで仕様
    を記述していきます。
    仕様フェーズで定めた仕様を
    ベ ー ス に Flutter チ ー ム と
    Railsチームが並行してそれ
    ぞれ開発作業を進めていきま
    す。
    実装フェーズで作成したもの
    をstaging環境にデプロイし
    て動作確認を行います。問題
    なければproduction環境に
    デプロイしてリリースを完了
    します。
    ①仕様フェーズ ②実装フェーズ ③連携フェーズ
    普段の開発の進め方
    最近つくった退会機能を例にして進め方を紹介しようと思います(ほんとは退会して
    ほしくないけどいつでも退会できるようにはしたいのでつくりました🥲)。
    

    View Slide

21. pocco-openapi
    pocco-flutter pocco-rails
    

    View Slide

22. ①仕様フェーズ
    どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ
    うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら
    仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに
    issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが
    OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し
    ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ
    ればこの段階で仕様の調整を追加で行います。pull requestがapproveされてmainに
    mergeされたらこのフェーズは完了になります。
    

    View Slide

23. ①仕様フェーズ
    どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ
    うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら
    仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに
    issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが
    OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し
    ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ
    ればこの段階で仕様の調整を追加で行います。pull requestがapproveされてmainに
    mergeされたらこのフェーズは完了になります。
    

    View Slide

24. View Slide

25. ①仕様フェーズ
    どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ
    うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら
    仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに
    issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが
    OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し
    ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ
    ればこの段階で仕様の調整を追加で行います。pull requestがapproveされてmainに
    mergeされたらこのフェーズは完了になります。
    

    View Slide

26. View Slide

27. View Slide

28. ①仕様フェーズ
    どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ
    うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら
    仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに
    issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが
    OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し
    ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ
    ればこの段階で仕様の調整を追加で行います。pull requestがapproveされてmainに
    mergeされたらこのフェーズは完了になります。
    

    View Slide

29. View Slide

30. View Slide

31. ①仕様フェーズ
    どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ
    うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら
    仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに
    issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが
    OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し
    ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ
    ればこの段階で仕様の調整を追加で行います。pull requestがapproveされてmainに
    mergeされたらこのフェーズは完了になります。
    

    View Slide

32. View Slide

33. ②実装フェーズ
    Flutterチーム側はRapidoc(Swagger UIの
    代替ツール)でAPIの仕様を確認しながら実
    装を進めていきます。Railsチーム側は
    committeeを使って仕様を満たしている
    ことを確認しながらAPIの開発を進めてい
    きます。
    WEB+DB-PRESS-Vol.108より引用
    

    View Slide

34. View Slide

35. View Slide

36. ③連携フェーズ
    APIの開発作業が完了したら、Railsチーム側ではstaging環境に変更をデプロイし、
    RailsチームからFlutterチームにその旨を連絡します。Flutterチーム側ではAPIサー
    バーとしてstaging環境を指定したアプリで動作確認を行います。動作確認で問題が
    なければRailsチーム側ではproduction環境に変更をデプロイし、Flutterチーム側で
    はApp Store/Google Playへの申請/公開を行います。これでリリースの完了です。
    

    View Slide

37. View Slide

38. 進め方のおさらい
    どのようなAPIが必要になる
    かを全員で議論してAPIの仕
    様を定めていきます。仕様が
    定まったらOpenAPIで仕様
    を記述していきます。
    仕様フェーズで定めた仕様を
    ベ ー ス に Flutter チ ー ム と
    Railsチームが並行してそれ
    ぞれ開発作業を進めていきま
    す。
    実装フェーズで作成したもの
    をstaging環境にデプロイし
    て動作確認を行います。問題
    なければproduction環境に
    デプロイしてリリースを完了
    します。
    ①仕様フェーズ ②実装フェーズ ③連携フェーズ
    このやり方はWEB+DB-PRESS-Vol.108を参考にしているのでもし興味がある方はそ
    ちらをぜひ読んでみてください。
    

    View Slide

39. どうなの
    

    View Slide

40. 仕様を記述するのは意外とカンタン
    OpenAPIのフォーマットがシンプルなので仕様を記述するのはそれほど大変ではあり
    ませんでした。YAMLを書くだけて見やすいドキュメント一式が手に入るので仕様を
    記述するコストも十分ペイすると考えられます。一方でリクエストやレスポンスで複
    雑な形式のJSONをやり取りするケースでは、OpenAPIでJSONのフォーマットを記
    述するのもその分だけ大変になります。PoccoではJSON:API(jsonapi.org)をフォー
    マットとして採用していたのでこの点がなかなか大変でした。OpenAPIにはスキーマ
    を再利用するためのcomponentsと呼ばれる仕組みがあるので、それを利用すること
    である程度はこの問題を緩和できているのではないかと思います。
    

    View Slide

41. 仕様と実装の乖離が起こりにくくなる
    仕様→実装の順に進めている限りは、実装が仕様に基づいていることはcommitteeに
    よって担保されるので、仕様と実装とが乖離するということは無くなります。普段の
    開発でも「ドキュメントと書いてあるのと違うんだけど...」といったことは一度もあ
    りませんでした。
    

    View Slide

42. 仕様を中心にコラボレーションできる
    OpenAPIはYAMLで書かれたただのファイルなので、ソースコードと同じように
    GitHub上で管理することができます。GitHub上で管理するようにすれば、普段の開
    発でやっているのと同じように、仕様の策定においてもコラボレーションすることが
    できます。今回は初めて一緒に仕事をするチームで、ぼくにとっては初めてのモバイ
    ルアプリ向けのAPI開発でしたが、GitHubフローに乗せられたおかげでFlutterチー
    ムとRailsチームが協力してAPIの仕様を考えることができました。いろいろ初めてだ
    けどうまくいったのは、この点が大きく寄与しているのかなと思います。
    

    View Slide

43. 参考文献
    

    View Slide

44. https://booth.pm/ja/items/1571902 https://gihyo.jp/magazine/wdpress/archive/2019/vol108
    

    View Slide