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. サービス&チームについて

5. None

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!