Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

Spring_MT
October 18, 2018

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

Spring_MT

October 18, 2018
Tweet

More Decks by Spring_MT

Other Decks in Technology

Transcript

  1. Swagger(OpenAPI 2.0)を使った

    API仕様Drivenな開発
    春⼭ 誠
    Makoto Haruyama
    銀座Rails
    #2

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  7. 開発タイムライン

    View full-size slide

  8. できるだけ早くかつ

    何度も検証プロセスを回したい

    View full-size slide

  9. 開発タイムライン

    View full-size slide

  10. 開発スピードをあげるには

    どうするのが最適?

    View full-size slide

  11. クライアントとサーバーの開発を

    なるべく並列で進められるようにする

    View full-size slide

  12. よくあるパターン

    View full-size slide

  13. 今回はこうしたい

    View full-size slide

  14. こうしてみました
    APIの仕様を開発時に利⽤しやすい形で整備する
    • メンテナンスがしやすいツールを導⼊
    • 開発時に参照しやすいようドキュメント化する
    • 実装と仕様書が乖離しないよう仕組み化して対応
    最初にMock APIを作って開発を並列で⾏えるようにする
    • クライアントがすぐに作業に着⼿できるように

    最初は簡単なmock APIを提供
    • 早くfeedbackをもらうことでサーバーサイドの⼿戻りを最⼩限に

    View full-size slide

  15. API仕様Drivenな開発

    View full-size slide

  16. APIの仕様をどうやって

    開発時に利⽤しやすい形でまとめるか?

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  20. 今だと⼀番候補になりそうですが、

    開発始めたときはそこまでたころは情報が少なかった
    今回、インフラやクライアントで挑戦していることも多く

    RESTから移⾏するための余裕がなかった
    同じリソースの内容を画⾯によってで出し分けるのであれば、
    graphQLがよさそう
    検討したツール
    graphQL

    View full-size slide

  21. Webクライアント(JS)で

    Protocol Bufferの扱い⽅が難しい
    grpc-webがでているが試してはいない
    検討したツール
    gRPC

    View full-size slide

  22. Swaggerを利⽤するための⼯夫

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  26. APIの仕様からドキュメントを⽣成する
    swagger-codegenを使って

    ドキュメントを⽣成
    github上でも確認できる

    ようにする

    View full-size slide

  27. RubyMineのSwagger plugin
    ⼊れることでRubyMine上で

    ドキュメントを⾒ながら開発できる

    View full-size slide

  28. APIの仕様をまとめるときに

    出てくる問題

    View full-size slide

  29. 仕様と実装の乖離

    仕様上にはあったが

    実装がもれている

    hotfixによる実装だけ⾏って

    仕様を更新していない

    View full-size slide

  30. Swaggerで定義した仕様と

    APIサーバーの実装を

    結合させることで

    実装と仕様書のズレが

    起こらないようにしたい

    View full-size slide

  31. SwaggerとAPIサーバの連携

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  35. これらをプロセスに組み込んだ

    開発フロー

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    1

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  43.    Swaggerのモックレスポンスをcontrollerにコピーしテストを通す
    Swagger Editorから

    コピーできる
    4

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  48. 振り返り

    View full-size slide

  49. 開発ボリューム
    管理画⾯ページ数

    60
    APIエンドポイント数

    30
    フロント画⾯数(SPA)

    40

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  52. クライアント側との振り返り
    今の所特に不満なし
    • ドキュメントが整備されていて実装しやすい

    今後はクライアント側のコードの

    ⾃動⽣成までサポートしてほしい
    • axios使っているのでそれに即したコードの⽣成

    View full-size slide

  53. 今後の課題
    Swaggerのファイル分割をスマートに
    • https://github.com/chuross/swaglow を検討する

    OpenAPI 3.0への対応
    • 3.0で対応される新しい仕様への対応(nullable等、今は⾃前で拡張)

    View full-size slide

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

    View full-size slide

  55. We are hiring!

    View full-size slide

  56. と⾔いたいのですが
    弊チームの計画上これ以上は。。

    View full-size slide

  57. https://dena.com/jp/recruit/career/engineer/
    DeNA is hiring!

    View full-size slide