DevelopersSummit2018_SwaggerでPHPエンジニアとUnityエンジニアがもっと仲良くなった話

2月15, 16日に行われたDevelopers Summit 2018にて発表したスライドになります。

Developers Summit 2018
http://event.shoeisha.jp/devsumi/20180215/

セッション概要
http://event.shoeisha.jp/devsumi/20180215/session/1687/

発表資料中で紹介しているエンジニアブログについては下記リンクから参照お願いします。
Swaggerを使ってAPIの繋ぎ込みを楽にするための取り組み
https://tech.griphone.co.jp/2017/10/08/swagger/

Swagger UI × Amazon EC2 × Dockerで開発初期からAPIの繋ぎ込みを意識できる環境を構築してみたhttps://tech.griphone.co.jp/2017/10/08/swagger-mock-server/

Transcript

1. 16-E-5 #devsumiE SwaggerでPHPエンジニアと Unityエンジニアがもっと仲良くなった話 株式会社グリフォン 仙道航 @Developers Summit 2018 2018/02/16
2. ⾃⼰紹介 仙道 航 株式会社グリフォン サーバサイドエンジニア 2015年4⽉ 株式会社サイバーエージェント 新卒⼊社 2015年7⽉ ゲーム事業部 (SGE) 株式会社グリフォンへ配属 ソーシャルゲームの運⽤に約⼀年携わる 2016年3⽉ PHP × Unity の新規開発プロジェクトへジョイン 2017年10⽉
3. 発表内容について 発表資料は後⽇共有されます！ メモなどを全て取ろうとしなくても⼤丈夫です！
4. もっと？ https://speakerdeck.com/sgeengineer/phpconference-lt- swaggerdephptounityenziniagazhong-liang-kunatutahua 今回はLTで発表した内容の深掘り版です！
5. アジェンダ 1. APIの繋ぎこみって⼤変！ 2. Swaggerの紹介 3. グリフォンでのSwagger活⽤事例
6. 1. APIの繋ぎこみって⼤変！
7. 開発あるある アプリやゲームの APIの繋ぎ込みは とても⼤変！
8. APIの繋ぎこみを⾏うまでのフロー 仕様書 / WFなどから作成するAPIの精査
9. APIの繋ぎこみを⾏うまでのフロー 仕様書 / WFなどから作成するAPIの精査 サーバ / クライアント間での認識合わせ
10. APIの繋ぎこみを⾏うまでのフロー 仕様書 / WFなどから作成するAPIの精査 サーバ / クライアント間での認識合わせ API / リクエスト / レスポンス部分の実装
11. APIの繋ぎこみを⾏うまでのフロー 仕様書 / WFなどから作成するAPIの精査 サーバ / クライアント間での認識合わせ API / リクエスト / レスポンス部分の実装 サーバ / クライアントでの繋ぎ込み
12. APIの繋ぎこみを⾏うまでのフロー 仕様書 / WFなどから作成するAPIの精査 サーバ / クライアント間での認識合わせ API / リクエスト / レスポンス部分の実装 サーバ / クライアントでの繋ぎ込み
13. 弊社で過去に⾏われたAPIの繋ぎ込み サーバ エンジニア クライアント エンジニア ①APIドキュメントを書く
14. APIを考えるとは？ 1. 何を⾏うためのAPIか？ 2. リクエストパラメータ 3. レスポンスパラメータ 4. エラーコード
15. APIドキュメント例 例: デッキ名を変更する
16. 弊社で過去に⾏われたAPIの繋ぎ込み サーバ エンジニア クライアント エンジニア ②ドキュメントを読みながら リクエスト,レスポンス部分 のクラス実装 ①APIドキュメントを書く
17. 弊社で過去に⾏われたAPIの繋ぎ込み サーバ エンジニア クライアント エンジニア ②ドキュメントを読みながら リクエスト,レスポンス部分 のクラス実装 ③~ API内容に更新や 不備があれば共有, 修正依頼 ①APIドキュメントを書く
18. 弊社で過去に⾏われたAPIの繋ぎ込みの問題 サーバ エンジニア クライアント エンジニア × 徐々に更新しなくなる！
19. 弊社で過去に⾏われたAPIの繋ぎ込みの問題 サーバ エンジニア クライアント エンジニア × 型や名前を⼿動で書くと ミスする → パースエラーの 原因に！ × 徐々に更新しなくなる！
20. 弊社で過去に⾏われたAPIの繋ぎ込みの問題 サーバ エンジニア クライアント エンジニア × 型や名前を⼿動で書くと ミスする → パースエラーの 原因に！ × ⼝頭によるその場しのぎ対応が 増えてドキュメントが置き去りに × 徐々に更新しなくなる！
21. これじゃ仲悪くなるよ・・・
23. 2. Swaggerについて
24. Swaggerとは？ REST APIを記述するための仕様と開発を 後押しするツールを提供しているフレーム ワーク 様々な団体がAPI記述のための標準フォー マットとして普及するよう推進している
25. Swaggerとは？ Googleトレンドでも伸びてきている！
26. Swaggerとは？ 弊社では3つのツールを利⽤している l Swagger Spec l Swagger UI l Swagger Codegen ଞʹ΋ͨ͘͞Μ͋ΔͷͰௐ΂ͯΈͯͶʂ 2.xܥ(stable)Λ ࢖ͬͯ·͢ʂ
27. Swagger Specとは？ YAML / JSON形式で記述できるAPIの設計図 [paths] エンドポイント, リクエスト, レスポンスの定義 [definitions] データ型の定義
28. Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義 API名
29. Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義 HTTP メソッド
30. Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義 APIの区分, タグ
31. Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義 APIの説明
32. Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義 リクエスト / レスポンスの データフォーマット
33. Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義 リクエストパラメータ
34. Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義 レスポンスパラメータ
35. Swagger Specとは？ [definitions] データ型の定義 データ型の名前
36. Swagger Specとは？ [definitions] データ型の定義 データ型の種類
37. Swagger Specとは？ [definitions] データ型の定義 データ型の説明
38. Swagger Specとは？ [definitions] データ型の定義 データ型の中⾝
39. Swagger Specとは？ [definitions] データ型の定義 データ型の中⾝は 複数指定もできる！
40. Swagger UIとは？ Swagger Specを基にした Web APIドキュメントを⽣成 リクエスト / レスポンス定義を 閲覧できる サンプルのレスポンスを返して くれるモック機能がある
41. Swagger UIとは？ http://petstore.swagger.io/?_ga=2.2822994 8.1082464866.1515850876- 167945699.1505133057
42. Swagger Codegenとは？ Swagger Specから様々な⾔語のクライアント / サーバのコードを⾃動⽣成してくれる などなど…
43. Swagger Codegenとは？ Swagger Specから様々な⾔語のクライアント / サーバのコードを⾃動⽣成してくれる ⾃動⽣成されるコードの雛形にはmustacheという テンプレートエンジンが使⽤されている
44. Swagger Codegenとは？ mustache（例 : C#のリクエストテンプレート） {{ hoge }} に Specのプロパティをマッピング
45. Swagger Codegenとは？ コード⽣成結果例 (例 : C#のリクエストクラス) {{ hoge }} に Specのプロパティをマッピング
46. 改善フロー サーバ エンジニア クライアント エンジニア ①Specを書く
47. 改善フロー サーバ エンジニア クライアント エンジニア ②⾃動⽣成 ①Specを書く ②⾃動⽣成 ②⾃動⽣成
48. 改善フロー サーバ エンジニア クライアント エンジニア ③~ API内容に更新や不備が あればSpecを修正, 修正依頼 ②⾃動⽣成 ①Specを書く ②⾃動⽣成 ②⾃動⽣成
49. 改善フローでのメリット サーバ エンジニア クライアント エンジニア ◦ 修正箇所が 集約された！
50. 改善フローでのメリット サーバ エンジニア クライアント エンジニア ◦ 修正箇所が 集約された！ ◦ ⾔語の違い 以外は同じ定義の コードが⽣成 される！
51. 改善フローでのメリット サーバ エンジニア クライアント エンジニア ◦ ドキュメントもコードも 置き去りにならない！ ◦ 修正箇所が 集約された！ ◦ ⾔語の違い 以外は同じ定義の コードが⽣成 される！
52. 少し仲良くなれそう！
53. 3. グリフォンでの Swagger活⽤事例について
54. グリフォンでのSwagger活⽤開発フロー 仕様書 / WFなどから作成するAPIの精査 サーバ / クライアント間での認識合わせ API / リクエスト / レスポンス部分の実装 サーバ / クライアントでの繋ぎ込み
55. グリフォンでのSwagger活⽤開発フロー 1. 仕様書 / WFなどから作成するAPIの精査 2. サーバ / クライアント間での認識合わせ 仕様書とWF, Swagger UIを⾒ながらMTG サーバエンジニアがSwagger Specを記述
56. グリフォンでのSwagger活⽤開発フロー 3. API / リクエスト / レスポンス部分の実装 PHPとC#のリクエスト / レスンポンスクラス / 共通で使⽤するEnumを⾃動⽣成 ⾃動⽣成されるコードに サーバ /クライアントから要望があった 使⽤するmustacheファイルを groovyスクリプトで切り替えながら⼀度に⾃動⽣成
57. 例えばこんな要望があった 型を厳密にするためにサーバで定義した型を 使いたい！ サーバ エンジニア 例えば・・・ CardLevel CardName ・初期化時必ずint型 ・1 ~ 100までの数値 ・初期化時必ずstring 型 ・10⽂字まで ・空⽂字は認めない
58. Swaggerで扱えるデータ型
59. Specification Extensionを使ったデータ型拡張 Specification Extensionとは？ x- から始まるユーザ独⾃のプロパティ
60. Specification Extensionを使ったデータ型拡張 Specification Extensionとは？ x- から始まるユーザ独⾃のプロパティ
61. Specification Extensionを使ったデータ型拡張 Specification Extensionとは？ x- から始まるユーザ独⾃のプロパティ ⾚枠 : x-serverType 緑枠 : x-serverNameSpaceList
62. Specification Extensionを使ったデータ型拡張 サーバ定義のクラスは変換メソッドを定義したインタフェー スを実装するようにしている レスポンス, リクエストクラス⽣成時に呼ばれて変換される仕組みに
63. Specification Extensionを使ったデータ型拡張 リクエスト, レスポンスのフロー クライアント Request 各機能コード Response 例: CardLevelを送って CardLevelを返してもらうだけ笑 ①intで送る
64. Specification Extensionを使ったデータ型拡張 リクエスト, レスポンスのフロー クライアント Request 各機能コード Response 例: CardLevelを送って CardLevelを返してもらうだけ笑 ①intで送る ② fromClientValueで サーバのクラスに変換
65. Specification Extensionを使ったデータ型拡張 リクエスト受け付け時に フレームワークから呼ばれて 各Controllerに渡される！
66. Specification Extensionを使ったデータ型拡張 リクエスト, レスポンスのフロー クライアント Request 各機能コード Response 例: CardLevelを送って CardLevelを返してもらうだけ笑 ①intで送る ② fromClientValueで サーバのクラスに変換 ③ 受け取ったサーバ定義 クラスで処理を⾏う
67. Specification Extensionを使ったデータ型拡張 リクエスト, レスポンスのフロー クライアント Request 各機能コード Response 例: CardLevelを送って CardLevelを返してもらうだけ笑 ①intで送る ② fromClientValueで サーバのクラスに変換 ③ 受け取ったサーバ定義 クラスで処理を⾏う ④ toClientValueで プリミティブ型に変換
68. Specification Extensionを使ったデータ型拡張 レスポンス送信時に フレームワークから呼ばれた後、 JSONに変換されクライアントに 渡される！
69. Specification Extensionを使ったデータ型拡張 リクエスト, レスポンスのフロー クライアント Request 各機能コード Response 例: CardLevelを送って CardLevelを返してもらうだけ笑 ①intで送る ② fromClientValueで サーバのクラスに変換 ③ 受け取ったサーバ定義 クラスで処理を⾏う ④ toClientValueで プリミティブ型に変換 ⑤intで返る
70. グリフォンでのSwagger活⽤開発フロー 4. サーバ / クライアントでの繋ぎ込み 開発初期 開発後 Swagger UIのモックAPI機能を使って 早い段階から繋ぎこみをしながら開発 PHPサーバと繋ぎ込み
71. グリフォンでのSwagger活⽤開発フロー サーバ クライアント × 8 Swagger リポジトリ ⾃動⽣成コード Submodule API定義記述
72. グリフォンでのSwagger活⽤開発フロー サーバ クライアント × 8 Swagger リポジトリ ⾃動⽣成コード Submodule API定義記述 push
73. グリフォンでのSwagger活⽤開発フロー サーバ クライアント × 8 Swagger リポジトリ ⾃動⽣成コード Submodule API定義記述 push 最新をpull APIモックをデプロイ ⾃動⽣成コードを push
74. グリフォンでのSwagger活⽤開発フロー サーバ クライアント × 8 Swagger リポジトリ ⾃動⽣成コード Submodule API定義記述 push 最新をpull APIモックをデプロイ ⾃動⽣成コードを push 既存開発部分のAPIに修正が⼊ると コード修正まで上⼿く動かなくなるので 複数バージョン環境を⽤意
75. グリフォンでのSwagger活⽤開発フロー サーバ クライアント × 8 Swagger リポジトリ ⾃動⽣成コード Submodule API定義記述 push 最新をpull APIモックをデプロイ ⾃動⽣成コードを push 接続先を開発フェーズで切り替え サーバ開発中
76. グリフォンでのSwagger活⽤開発フロー Unity上で簡単切り替え
77. グリフォンでのSwagger活⽤開発フロー サーバ クライアント × 8 Swagger リポジトリ ⾃動⽣成コード Submodule API定義記述 push 最新をpull APIモックをデプロイ ⾃動⽣成コードを push 接続先を開発フェーズで切り替え サーバ開発中 サーバ開発後 PHPコード デプロイ
78. グリフォンでのSwagger活⽤開発フロー 4. サーバ / クライアントでの繋ぎ込み 開発初期 開発後 Swagger UIのモックAPI機能を使って 早い段階から繋ぎこみをしながら開発 PHPサーバと繋ぎ込み 疎通に使うリクエスト / レスポンス定義は 同じなのでスムーズに繋ぎ込める！
79. 仲良しに！
80. 運⽤してみて気づいた点 プロジェクトの規約ややりたいことに合わせた コード⽣成は少し敷居が⾼いかも 改造するものがたくさん！ (mustache, codegen(java), ⽣成スクリプトなど) Swagger Specの記述, ファイル分割の規約は きちんと決めた⽅がいい 何もしないとメンテ不能なyamlが簡単にできます！ (,,ﾟДﾟ)笑
81. グリフォンエンジニアブログもお願いします！ https://tech.griphone.co.jp/2017/1 0/08/swagger https://tech.griphone.co.jp/2017/1 0/08/swagger-mock-server
82. まとめ Swaggerを利⽤してAPI繋ぎこみのつらさを 軽減する話をしました 弊社のエンジニアブログもぜひ参照してみて ください！ https://tech.griphone.co.jp グリフォン エンジニアブログ で検索！
83. おしまい ご清聴 ありがとう ございました！