Pro Yearly is on sale from $80 to $50! »

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

Aa777465acd82d13333678f3fc082c59?s=47 Spring_MT
October 18, 2018

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

Aa777465acd82d13333678f3fc082c59?s=128

Spring_MT

October 18, 2018
Tweet

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!