$30 off During Our Annual Pro Sale. View Details »

OpenAPI? What Is That? Is That Tasty?

Shohei Umemoto
October 29, 2021
1.8k

OpenAPI? What Is That? Is That Tasty?

Shohei Umemoto

October 29, 2021
Tweet

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