Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
OpenAPI? What Is That? Is That Tasty?
Search
Shohei Umemoto
October 29, 2021
4
2k
OpenAPI? What Is That? Is That Tasty?
Shohei Umemoto
October 29, 2021
Tweet
Share
More Decks by Shohei Umemoto
See All by Shohei Umemoto
Schema-first API Development with OpenAPI and Committee
cafedomancer
0
80
Just Tried Stimulus
cafedomancer
3
970
Ruby Can Learn Something A Little
cafedomancer
2
340
How To Use Gensim
cafedomancer
3
580
Featured
See All Featured
How to Ace a Technical Interview
jacobian
275
23k
Fontdeck: Realign not Redesign
paulrobertlloyd
80
5.1k
Documentation Writing (for coders)
carmenintech
65
4.3k
The MySQL Ecosystem @ GitHub 2015
samlambert
250
12k
Java REST API Framework Comparison - PWX 2021
mraible
PRO
27
7.4k
WebSockets: Embracing the real-time Web
robhawkes
59
7.3k
What the flash - Photography Introduction
edds
67
11k
How GitHub Uses GitHub to Build GitHub
holman
472
290k
Building Better People: How to give real-time feedback that sticks.
wjessup
359
18k
Art, The Web, and Tiny UX
lynnandtonic
294
20k
The Brand Is Dead. Long Live the Brand.
mthomps
53
37k
Into the Great Unknown - MozCon
thekraken
28
1.4k
Transcript
OpenAPI? なにそれ? おいしいの? 2021/10/29 えにしテック永和技術交流会 @cafedomancer
Shohei Umemoto @cafedomancer えにしテックでプログラマをや っています。2015年10月に新 卒入社したのでちょうど7年目 になります。さいきんの趣味は ヤマノススメの影響ではじめた 登山です。もうすぐ30歳になる ので記念に富士山にのぼってみ
たい!
Pocco
None
Poccoについて 北海道産の食材を使用したアイスを定期便としてお届けするサービスです。コロッケ さん(corock.co)が運営するサービスで、えにしテックが技術支援する形で進めてい ます。もともとはShopifyで販売を行っていたのですが、モバイルアプリとしてサー ビスを提供することになり、2020年10月ごろから新規プロジェクトとして開発をス タートしました。フロントエンドはFlutter、バックエンドはRailsで作られており、 REST APIを介してやり取りする形になっています。開発もそれぞれのチームに分か れて行っています。えにしテックでは主にバックエンドのRailsを中心として開発を 行っています。
None
REST API
えにしテック コロッケさん 業務委託の方 (北海道) (北海道) (東京・大阪)
OpenAPIをやることになったキッカケ Flutterチームの方が「REST API の仕様をドキュメントとして記述してほしい。 OpenAPIかなにかで書いてもらえると助かる。」とおっしゃられました。しかしその 当時ぼくはOpenAPIについてよく知らなかったので、とりあえず「わかりました!こ ちらで方法を検討してみます!」とお返事しました。それがキッカケでOpenAPIを用 いた開発のやり方を調べ始めることになりました。正直なところOpenAPIで仕様を書 くなんてやったことないしめんどくさそうと当初は思っていたのですが、やってみた ら結構よかったので、今日はそのことについてお話ししていこうと思います。
えにしテック 業務委託の方 OpenAPI か な に かでREST APIの 仕様を書いても らえると助かる
のですが... わかりました! こちらでやり方 を考えてみます ね! (OpenAPIとかや ったことないし なんかめんどく さそう...)
None
OpenAPI
OpenAPIについて REST APIの仕様をYAMLまたはJSONで記述するためのフォーマットです。パス・ HTTPメソッド・ステータスコード・Content-Type・リクエスト・レスポンスなど を仕様として記述することができます。Swagger EditorやSwagger UI、Swagger Codegenといったツール群と合わせて使用します。実際に見てみたほうが分かりやす いと思うので、Swagger EditorとSwagger
UIについてデモを行います。Swagger CodegenについてはPoccoのプロジェクトでは使用していないので、今日の発表でも 扱わないことにします。cafedomancer/petstoreにOpenAPIで記述した仕様を載せ ているので、全体を見てみたい方はそちらをのぞいてみてください。
None
None
RailsとOpenAPIを組み合わせてつかう committee(committee-rails)というgemを使うことで、リクエストとレスポンスが OpeAPIで記述した仕様にしたがっているかを、request specまたはintegration testでチェックすることができます。実際にどのように使用するのかをデモを行いな がら説明します。cafedomancer/petstoreにコードを掲載しているので、細かい部 分も見てみたい方はそちらをのぞいてみてください。
None
None
やりかた
どのようなAPIが必要になる かを全員で議論してAPIの仕 様を定めていきます。仕様が 定まったらOpenAPIで仕様 を記述していきます。 仕様フェーズで定めた仕様を ベ ー ス に
Flutter チ ー ム と Railsチームが並行してそれ ぞれ開発作業を進めていきま す。 実装フェーズで作成したもの をstaging環境にデプロイし て動作確認を行います。問題 なければproduction環境に デプロイしてリリースを完了 します。 ①仕様フェーズ ②実装フェーズ ③連携フェーズ 普段の開発の進め方 最近つくった退会機能を例にして進め方を紹介しようと思います(ほんとは退会して ほしくないけどいつでも退会できるようにはしたいのでつくりました🥲)。
pocco-openapi pocco-flutter pocco-rails
①仕様フェーズ どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら 仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ ればこの段階で仕様の調整を追加で行います。pull
requestがapproveされてmainに mergeされたらこのフェーズは完了になります。
①仕様フェーズ どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら 仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ ればこの段階で仕様の調整を追加で行います。pull
requestがapproveされてmainに mergeされたらこのフェーズは完了になります。
None
①仕様フェーズ どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら 仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ ればこの段階で仕様の調整を追加で行います。pull
requestがapproveされてmainに mergeされたらこのフェーズは完了になります。
None
None
①仕様フェーズ どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら 仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ ればこの段階で仕様の調整を追加で行います。pull
requestがapproveされてmainに mergeされたらこのフェーズは完了になります。
None
None
①仕様フェーズ どのようなAPIが必要になるか、どのようなタイミングでAPIを呼び出すか、どのよ うな形式のデータをやり取りするかなどを、画面をベースにして全員で議論しながら 仕様を考えます。ざっくりとした見通しが立ったらpocco-openapiリポジトリに issueを立てて細かい部分の仕様を詰めていきます。それと合わせてRailsチームが OpenAPIで仕様を記述してpocco-openapiリポジトリに対してpull requestを作成し ます。作成したpull requestはFlutterチームにレビューしてもらいます。必要があ ればこの段階で仕様の調整を追加で行います。pull
requestがapproveされてmainに mergeされたらこのフェーズは完了になります。
None
②実装フェーズ Flutterチーム側はRapidoc(Swagger UIの 代替ツール)でAPIの仕様を確認しながら実 装を進めていきます。Railsチーム側は committeeを使って仕様を満たしている ことを確認しながらAPIの開発を進めてい きます。 WEB+DB-PRESS-Vol.108より引用
None
None
③連携フェーズ APIの開発作業が完了したら、Railsチーム側ではstaging環境に変更をデプロイし、 RailsチームからFlutterチームにその旨を連絡します。Flutterチーム側ではAPIサー バーとしてstaging環境を指定したアプリで動作確認を行います。動作確認で問題が なければRailsチーム側ではproduction環境に変更をデプロイし、Flutterチーム側で はApp Store/Google Playへの申請/公開を行います。これでリリースの完了です。
None
進め方のおさらい どのようなAPIが必要になる かを全員で議論してAPIの仕 様を定めていきます。仕様が 定まったらOpenAPIで仕様 を記述していきます。 仕様フェーズで定めた仕様を ベ ー ス
に Flutter チ ー ム と Railsチームが並行してそれ ぞれ開発作業を進めていきま す。 実装フェーズで作成したもの をstaging環境にデプロイし て動作確認を行います。問題 なければproduction環境に デプロイしてリリースを完了 します。 ①仕様フェーズ ②実装フェーズ ③連携フェーズ このやり方はWEB+DB-PRESS-Vol.108を参考にしているのでもし興味がある方はそ ちらをぜひ読んでみてください。
どうなの
仕様を記述するのは意外とカンタン OpenAPIのフォーマットがシンプルなので仕様を記述するのはそれほど大変ではあり ませんでした。YAMLを書くだけて見やすいドキュメント一式が手に入るので仕様を 記述するコストも十分ペイすると考えられます。一方でリクエストやレスポンスで複 雑な形式のJSONをやり取りするケースでは、OpenAPIでJSONのフォーマットを記 述するのもその分だけ大変になります。PoccoではJSON:API(jsonapi.org)をフォー マットとして採用していたのでこの点がなかなか大変でした。OpenAPIにはスキーマ を再利用するためのcomponentsと呼ばれる仕組みがあるので、それを利用すること である程度はこの問題を緩和できているのではないかと思います。
仕様と実装の乖離が起こりにくくなる 仕様→実装の順に進めている限りは、実装が仕様に基づいていることはcommitteeに よって担保されるので、仕様と実装とが乖離するということは無くなります。普段の 開発でも「ドキュメントと書いてあるのと違うんだけど...」といったことは一度もあ りませんでした。
仕様を中心にコラボレーションできる OpenAPIはYAMLで書かれたただのファイルなので、ソースコードと同じように GitHub上で管理することができます。GitHub上で管理するようにすれば、普段の開 発でやっているのと同じように、仕様の策定においてもコラボレーションすることが できます。今回は初めて一緒に仕事をするチームで、ぼくにとっては初めてのモバイ ルアプリ向けのAPI開発でしたが、GitHubフローに乗せられたおかげでFlutterチー ムとRailsチームが協力してAPIの仕様を考えることができました。いろいろ初めてだ けどうまくいったのは、この点が大きく寄与しているのかなと思います。
参考文献
https://booth.pm/ja/items/1571902 https://gihyo.jp/magazine/wdpress/archive/2019/vol108