Swagger (OpenAPI 2.0) を使ったAPI仕様Drivenな開発 / API-Spec-Driven development with Swagger

Transcript

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