Swagger(OpenAPI 2.0)を使った API仕様Drivenな開発春⼭ 誠Makoto Haruyama銀座Rails#2
View Slide
2008 - DeNA⼊社2010 - エンジニアに転向2011 - DeNA退社 → 福岡で新規サービス⽴ち上げ2013 - DeNAに出戻り2016 - ゲーム事業本部2017 - コマース&インキュベーション事業本部SpringMT Spring_MT春⼭ 誠Makoto Haruyama
サービス&チームについてAPI仕様Drivenな開発• Swaggerを取り⼊れた開発フローについて振り返り• 開発スケジュール/不具合はどうだったか/QAからのフィードバック• 今後の課題まとめ⽬次
サービス&チームについて
メンバー構成全体で5名開発メンバーは2名• サーバー∕インフラ担当 — 1名• クライアント担当 —---------1名
サービスの構成APIサーバー• Railsクライアント• 設計段階からWeb, iOS, Androidに対応することを想定• 少⼈数で対応することを考えて初期からReact Nativeの採⽤を検討• Web(JS)はReactベースのSPA (APIサーバーとは独⽴)
開発タイムライン
できるだけ早くかつ 何度も検証プロセスを回したい
開発スピードをあげるには どうするのが最適？
クライアントとサーバーの開発を なるべく並列で進められるようにする
よくあるパターン
今回はこうしたい
こうしてみましたAPIの仕様を開発時に利⽤しやすい形で整備する• メンテナンスがしやすいツールを導⼊• 開発時に参照しやすいようドキュメント化する• 実装と仕様書が乖離しないよう仕組み化して対応最初にMock APIを作って開発を並列で⾏えるようにする• クライアントがすぐに作業に着⼿できるように 最初は簡単なmock APIを提供• 早くfeedbackをもらうことでサーバーサイドの⼿戻りを最⼩限に
API仕様Drivenな開発
APIの仕様をどうやって 開発時に利⽤しやすい形でまとめるか？
APIの仕様として最初に決める必要があるものリクエスト情報• path, method, content type, path parameter, bodyレスポンス情報• content type, body
APIの仕様をどうまとめるかツールを利⽤• Swagger（今回採⽤）• graphQL• gRPC
YAMLで仕様をかけるドキュメント⽣成RESTベースクライアント⽣成データに対して、JSON Schema⽣成できるRailsへ組み込むgem(committee)ありAPIのmockが作りやすい検討したツールSwagger
今だと⼀番候補になりそうですが、 開発始めたときはそこまでたころは情報が少なかった今回、インフラやクライアントで挑戦していることも多く RESTから移⾏するための余裕がなかった同じリソースの内容を画⾯によってで出し分けるのであれば、graphQLがよさそう検討したツールgraphQL
Webクライアント（JS）で Protocol Bufferの扱い⽅が難しいgrpc-webがでているが試してはいない検討したツールgRPC
Swaggerを利⽤するための⼯夫
可読性を⾼めてAPIの仕様をまとめるyamlで書けるまとめて1つのファイルに書くと可読性が悪いので…
multi-file-swaggeryamlファイルを分割し、最終的に⼀つのschema.yamlにまとめることができる
multi-file-swaggeryamlファイルの構成例paths• エンドポイントごとの定義を書くshared• 共通のmodelなどを格納
APIの仕様からドキュメントを⽣成するswagger-codegenを使って ドキュメントを⽣成github上でも確認できる ようにする
RubyMineのSwagger plugin⼊れることでRubyMine上で ドキュメントを⾒ながら開発できる
APIの仕様をまとめるときに 出てくる問題
仕様と実装の乖離•仕様上にはあったが 実装がもれている•hotfixによる実装だけ⾏って 仕様を更新していない
Swaggerで定義した仕様と APIサーバーの実装を 結合させることで 実装と仕様書のズレが 起こらないようにしたい
SwaggerとAPIサーバの連携
APIサーバーと連携するcommitteeを使ってRailsに組み込む•https://github.com/interagent/committee
committeeを利⽤してできることリクエストのバリデーション• リクエストの内容をSwaggerで⽣成されるJSON Schemaを使ってバリデーションレスポンスの⽣成とバリデーション• View作らずに、Swaggerの定義通りにレスポンスを⽣成する• Jbuilderとかは使わない• レスポンスの内容をSwaggerで⽣成されるJSON Schemaを使ってバリデーション
レスポンスの⽣成schemaのプロパティを使って⾃動⽣成• レスポンスのパラメータ追加ならコード変更はいらない
これらをプロセスに組み込んだ 開発フロー
開発フロー1. 画⾯仕様の決定2. SwaggerでAPIの仕様を起こす3. サーバー側でルーティングを⾜してテストを書きテストを落とす4. Swaggerのモックレスポンスをcontrollerにコピーしてテストを通す5. マージしてsandbox環境でデプロイする6. クライアントとサーバーの開発開始123456
開発フローʙ࣌ؒ͘Β͍ͰରԠ͢Δ1. 画⾯仕様の決定2. SwaggerでAPIの仕様を起こす3. サーバー側でルーティングを⾜してテストを書きテストを落とす4. Swaggerのモックレスポンスをcontrollerにコピーしてテストを通す5. マージしてsandbox環境でデプロイする6. クライアントとサーバーの開発開始123456
画⾯仕様の決定ProductRequirementからAPIの設計をする1
SwaggerでAPIの仕様を起こすSwaggerの書き⽅に準じて書くだけ2
サーバー側でRoutingを⾜してテストを書きテストを落とす最⼩限の実装3
サーバー側でRoutingを⾜してテストを書きテストを落とす実装ないので落ちる最⼩限のテスト3
サーバー側でRoutingを⾜してテストを書きテストを落とす3
Swaggerのモックレスポンスをcontrollerにコピーしテストを通すSwagger Editorから コピーできる4
Swaggerのモックレスポンスをcontrollerにコピーしテストを通す4
mergeしてsandbox環境でデプロイするSandbox deploy• Sandbox環境へはローカルからdeployできる5
サーバーとクライアントの実装開始ここからちゃんとした実装開始• サーバーはDBの設計とかロジックを書いていく• クライアントはダミーのレスポンスをもとに画⾯を作っていく6
振り返り
開発ボリューム管理画⾯ページ数 60APIエンドポイント数 30フロント画⾯数(SPA) 40
β版リリースまでのスケジュールβリリース後も機能追加や本リリース向けの対応を⾏っている
不具合
QAチームとの振り返りDeNAの中で⽐較すると全体的に品質が⾼いと⾼評価• APIの不具合はほとんどなし• 上がってきたものはQAで拾う想定だった⽂⾔やレイアウトの問題
クライアント側との振り返り今の所特に不満なし• ドキュメントが整備されていて実装しやすい 今後はクライアント側のコードの ⾃動⽣成までサポートしてほしい• axios使っているのでそれに即したコードの⽣成
今後の課題Swaggerのファイル分割をスマートに• https://github.com/chuross/swaglow を検討する OpenAPI 3.0への対応• 3.0で対応される新しい仕様への対応(nullable等、今は⾃前で拡張)
まとめ
まとめSwaggerを使ったAPI仕様ファーストで開発スピードを向上できたさらにSwaggerとサーバーを組み合わせることで、開発スピードの向上と不具合の減少に寄与することができた
We are hiring!
と⾔いたいのですが弊チームの計画上これ以上は。。
https://dena.com/jp/recruit/career/engineer/DeNA is hiring!
spring_mt
muno92
okunokentaro
tomohisa
takahashikazutaro
gen519
kentosuzuki
udzura
uzulla
iseki
makamaka
tatematsu_san
oracle4engineer
cromwellryan
cassininazir
thoeni
bkeepers
shpigford
denniskardys
edds
tanoku
holman
orderedlist
vanstee
productmarketing