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

by Spring_MT

Slide 1

Slide 1 text

Swagger(OpenAPI 2.0)を使った  API仕様Drivenな開発春⼭誠 Makoto Haruyama 銀座Rails #2

Slide 2

Slide 2 text

2008 - DeNA⼊社 2010 - エンジニアに転向 2011 - DeNA退社 → 福岡で新規サービス⽴ち上げ 2013 - DeNAに出戻り 2016 - ゲーム事業本部 2017 - コマース&インキュベーション事業本部 SpringMT Spring_MT 春⼭誠 Makoto Haruyama

Slide 3

Slide 3 text

サービス&チームについて API仕様Drivenな開発 • Swaggerを取り⼊れた開発フローについて振り返り • 開発スケジュール/不具合はどうだったか/QAからのフィードバック • 今後の課題まとめ⽬次

Slide 4

Slide 4 text

サービス&チームについて

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

メンバー構成全体で5名開発メンバーは2名 • サーバー∕インフラ担当 — 1名 • クライアント担当 —---------1名

Slide 7

Slide 7 text

サービスの構成 APIサーバー • Rails クライアント • 設計段階からWeb, iOS, Androidに対応することを想定 • 少⼈数で対応することを考えて初期からReact Nativeの採⽤を検討 • Web(JS)はReactベースのSPA (APIサーバーとは独⽴)

Slide 8

Slide 8 text

開発タイムライン

Slide 9

Slide 9 text

できるだけ早くかつ  何度も検証プロセスを回したい

Slide 10

Slide 10 text

開発タイムライン

Slide 11

Slide 11 text

開発スピードをあげるには  どうするのが最適？

Slide 12

Slide 12 text

クライアントとサーバーの開発を  なるべく並列で進められるようにする

Slide 13

Slide 13 text

よくあるパターン

Slide 14

Slide 14 text

今回はこうしたい

Slide 15

Slide 15 text

こうしてみました APIの仕様を開発時に利⽤しやすい形で整備する • メンテナンスがしやすいツールを導⼊ • 開発時に参照しやすいようドキュメント化する • 実装と仕様書が乖離しないよう仕組み化して対応最初にMock APIを作って開発を並列で⾏えるようにする • クライアントがすぐに作業に着⼿できるように  最初は簡単なmock APIを提供 • 早くfeedbackをもらうことでサーバーサイドの⼿戻りを最⼩限に

Slide 16

Slide 16 text

API仕様Drivenな開発

Slide 17

Slide 17 text

APIの仕様をどうやって  開発時に利⽤しやすい形でまとめるか？

Slide 18

Slide 18 text

APIの仕様として最初に決める必要があるものリクエスト情報 • path, method, content type, path parameter, body レスポンス情報 • content type, body

Slide 19

Slide 19 text

APIの仕様をどうまとめるかツールを利⽤ • Swagger（今回採⽤） • graphQL • gRPC

Slide 20

Slide 20 text

YAMLで仕様をかけるドキュメント⽣成 RESTベースクライアント⽣成データに対して、JSON Schema⽣成できる Railsへ組み込むgem(committee)あり APIのmockが作りやすい検討したツール Swagger

Slide 21

Slide 21 text

今だと⼀番候補になりそうですが、  開発始めたときはそこまでたころは情報が少なかった今回、インフラやクライアントで挑戦していることも多く  RESTから移⾏するための余裕がなかった同じリソースの内容を画⾯によってで出し分けるのであれば、 graphQLがよさそう検討したツール graphQL

Slide 22

Slide 22 text

Webクライアント（JS）で  Protocol Buﬀerの扱い⽅が難しい grpc-webがでているが試してはいない検討したツール gRPC

Slide 23

Slide 23 text

Swaggerを利⽤するための⼯夫

Slide 24

Slide 24 text

可読性を⾼めてAPIの仕様をまとめる yamlで書けるまとめて1つのファイルに書くと可読性が悪いので…

Slide 25

Slide 25 text

multi-ﬁle-swagger yamlファイルを分割し、最終的に⼀つのschema.yamlにまとめることができる

Slide 26

Slide 26 text

multi-ﬁle-swagger yamlファイルの構成例 paths • エンドポイントごとの定義を書く shared • 共通のmodelなどを格納

Slide 27

Slide 27 text

APIの仕様からドキュメントを⽣成する swagger-codegenを使って  ドキュメントを⽣成 github上でも確認できる  ようにする

Slide 28

Slide 28 text

RubyMineのSwagger plugin ⼊れることでRubyMine上で  ドキュメントを⾒ながら開発できる

Slide 29

Slide 29 text

APIの仕様をまとめるときに  出てくる問題

Slide 30

Slide 30 text

仕様と実装の乖離 • 仕様上にはあったが  実装がもれている • hotﬁxによる実装だけ⾏って  仕様を更新していない

Slide 31

Slide 31 text

Swaggerで定義した仕様と  APIサーバーの実装を  結合させることで  実装と仕様書のズレが  起こらないようにしたい

Slide 32

Slide 32 text

SwaggerとAPIサーバの連携

Slide 33

Slide 33 text

APIサーバーと連携する committeeを使ってRailsに組み込む •https://github.com/interagent/committee

Slide 34

Slide 34 text

committeeを利⽤してできることリクエストのバリデーション • リクエストの内容をSwaggerで⽣成されるJSON Schemaを使ってバリデーションレスポンスの⽣成とバリデーション • View作らずに、Swaggerの定義通りにレスポンスを⽣成する • Jbuilderとかは使わない • レスポンスの内容をSwaggerで⽣成されるJSON Schemaを使ってバリデーション

Slide 35

Slide 35 text

レスポンスの⽣成 schemaのプロパティを使って⾃動⽣成 • レスポンスのパラメータ追加ならコード変更はいらない

Slide 36

Slide 36 text

これらをプロセスに組み込んだ  開発フロー

Slide 37

Slide 37 text

開発フロー 1. 画⾯仕様の決定 2. SwaggerでAPIの仕様を起こす 3. サーバー側でルーティングを⾜してテストを書きテストを落とす 4. Swaggerのモックレスポンスをcontrollerにコピーしてテストを通す 5. マージしてsandbox環境でデプロイする 6. クライアントとサーバーの開発開始 1 2 3 4 5 6

Slide 38

Slide 38 text

開発フロー ʙ͸࣌ؒ͘Β͍ͰରԠ͢Δ 1. 画⾯仕様の決定 2. SwaggerでAPIの仕様を起こす 3. サーバー側でルーティングを⾜してテストを書きテストを落とす 4. Swaggerのモックレスポンスをcontrollerにコピーしてテストを通す 5. マージしてsandbox環境でデプロイする 6. クライアントとサーバーの開発開始 1 2 3 4 5 6

Slide 39

Slide 39 text

画⾯仕様の決定 Product RequirementからAPIの設計をする 1

Slide 40

Slide 40 text

SwaggerでAPIの仕様を起こす Swaggerの書き⽅に準じて書くだけ 2

Slide 41

Slide 41 text

サーバー側でRoutingを⾜してテストを書きテストを落とす最⼩限の実装 3

Slide 42

Slide 42 text

サーバー側でRoutingを⾜してテストを書きテストを落とす実装ないので落ちる最⼩限のテスト 3

Slide 43

Slide 43 text

サーバー側でRoutingを⾜してテストを書きテストを落とす 3

Slide 44

Slide 44 text

Swaggerのモックレスポンスをcontrollerにコピーしテストを通す Swagger Editorから  コピーできる 4

Slide 45

Slide 45 text

Swaggerのモックレスポンスをcontrollerにコピーしテストを通す 4

Slide 46

Slide 46 text

Swaggerのモックレスポンスをcontrollerにコピーしテストを通す 4

Slide 47

Slide 47 text

mergeしてsandbox環境でデプロイする Sandbox deploy • Sandbox環境へはローカルからdeployできる 5

Slide 48

Slide 48 text

サーバーとクライアントの実装開始ここからちゃんとした実装開始 • サーバーはDBの設計とかロジックを書いていく • クライアントはダミーのレスポンスをもとに画⾯を作っていく 6

Slide 49

Slide 49 text

振り返り

Slide 50

Slide 50 text

開発ボリューム管理画⾯ページ数  60 APIエンドポイント数  30 フロント画⾯数(SPA)  40

Slide 51

Slide 51 text

β版リリースまでのスケジュール βリリース後も機能追加や本リリース向けの対応を⾏っている

Slide 52

Slide 52 text

不具合

Slide 53

Slide 53 text

QAチームとの振り返り DeNAの中で⽐較すると全体的に品質が⾼いと⾼評価 • APIの不具合はほとんどなし • 上がってきたものはQAで拾う想定だった⽂⾔やレイアウトの問題

Slide 54

Slide 54 text

クライアント側との振り返り今の所特に不満なし • ドキュメントが整備されていて実装しやすい  今後はクライアント側のコードの  ⾃動⽣成までサポートしてほしい • axios使っているのでそれに即したコードの⽣成

Slide 55

Slide 55 text

今後の課題 Swaggerのファイル分割をスマートに • https://github.com/chuross/swaglow を検討する  OpenAPI 3.0への対応 • 3.0で対応される新しい仕様への対応(nullable等、今は⾃前で拡張)

Slide 56

Slide 56 text

まとめ

Slide 57

Slide 57 text

まとめ Swaggerを使ったAPI仕様ファーストで開発スピードを向上できたさらにSwaggerとサーバーを組み合わせることで、開発スピードの向上と不具合の減少に寄与することができた