OpenAPI? What Is That? Is That Tasty?

Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

Pocco

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

No content

Slide 7

Slide 7 text

REST API

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

No content

Slide 12

Slide 12 text

OpenAPI

Slide 13

Slide 13 text

OpenAPIについて REST APIの仕様をYAMLまたはJSONで記述するためのフォーマットです。パス・ HTTPメソッド・ステータスコード・Content-Type・リクエスト・レスポンスなどを仕様として記述することができます。Swagger EditorやSwagger UI、Swagger Codegenといったツール群と合わせて使用します。実際に見てみたほうが分かりやすいと思うので、Swagger EditorとSwagger UIについてデモを行います。Swagger CodegenについてはPoccoのプロジェクトでは使用していないので、今日の発表でも扱わないことにします。cafedomancer/petstoreにOpenAPIで記述した仕様を載せているので、全体を見てみたい方はそちらをのぞいてみてください。

Slide 14

Slide 14 text

No content

Slide 15

Slide 15 text

No content

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

No content

Slide 18

Slide 18 text

No content

Slide 19

Slide 19 text

やりかた

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

pocco-openapi pocco-flutter pocco-rails

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

Slide 24

Slide 24 text

No content

Slide 25

Slide 25 text

Slide 26

Slide 26 text

No content

Slide 27

Slide 27 text

No content

Slide 28

Slide 28 text

Slide 29

Slide 29 text

No content

Slide 30

Slide 30 text

No content

Slide 31

Slide 31 text

Slide 32

Slide 32 text

No content

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

No content

Slide 35

Slide 35 text

No content

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

No content

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

どうなの

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

参考文献

Slide 44

Slide 44 text

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