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

by CyberAgent SGE Engineer

Slide 1

Slide 1 text

16-E-5 #devsumiE SwaggerでPHPエンジニアと Unityエンジニアがもっと仲良くなった話株式会社グリフォン仙道航 @Developers Summit 2018 2018/02/16

Slide 2

Slide 2 text

⾃⼰紹介仙道航株式会社グリフォンサーバサイドエンジニア 2015年4⽉株式会社サイバーエージェント新卒⼊社 2015年7⽉ゲーム事業部 (SGE) 株式会社グリフォンへ配属ソーシャルゲームの運⽤に約⼀年携わる 2016年3⽉ PHP × Unity の新規開発プロジェクトへジョイン 2017年10⽉

Slide 3

Slide 3 text

発表内容について発表資料は後⽇共有されます！メモなどを全て取ろうとしなくても⼤丈夫です！

Slide 4

Slide 4 text

もっと？ https://speakerdeck.com/sgeengineer/phpconference-lt- swaggerdephptounityenziniagazhong-liang-kunatutahua 今回はLTで発表した内容の深掘り版です！

Slide 5

Slide 5 text

アジェンダ 1. APIの繋ぎこみって⼤変！ 2. Swaggerの紹介 3. グリフォンでのSwagger活⽤事例

Slide 6

Slide 6 text

1. APIの繋ぎこみって⼤変！

Slide 7

Slide 7 text

開発あるあるアプリやゲームの APIの繋ぎ込みはとても⼤変！

Slide 8

Slide 8 text

APIの繋ぎこみを⾏うまでのフロー仕様書 / WFなどから作成するAPIの精査

Slide 9

Slide 9 text

APIの繋ぎこみを⾏うまでのフロー仕様書 / WFなどから作成するAPIの精査サーバ / クライアント間での認識合わせ

Slide 10

Slide 10 text

APIの繋ぎこみを⾏うまでのフロー仕様書 / WFなどから作成するAPIの精査サーバ / クライアント間での認識合わせ API / リクエスト / レスポンス部分の実装

Slide 11

Slide 11 text

APIの繋ぎこみを⾏うまでのフロー仕様書 / WFなどから作成するAPIの精査サーバ / クライアント間での認識合わせ API / リクエスト / レスポンス部分の実装サーバ / クライアントでの繋ぎ込み

Slide 12

Slide 12 text

Slide 13

Slide 13 text

弊社で過去に⾏われたAPIの繋ぎ込みサーバエンジニアクライアントエンジニア ①APIドキュメントを書く

Slide 14

Slide 14 text

APIを考えるとは？ 1. 何を⾏うためのAPIか？ 2. リクエストパラメータ 3. レスポンスパラメータ 4. エラーコード

Slide 15

Slide 15 text

APIドキュメント例例: デッキ名を変更する

Slide 16

Slide 16 text

弊社で過去に⾏われたAPIの繋ぎ込みサーバエンジニアクライアントエンジニア ②ドキュメントを読みながらリクエスト,レスポンス部分のクラス実装 ①APIドキュメントを書く

Slide 17

Slide 17 text

弊社で過去に⾏われたAPIの繋ぎ込みサーバエンジニアクライアントエンジニア ②ドキュメントを読みながらリクエスト,レスポンス部分のクラス実装 ③~ API内容に更新や不備があれば共有, 修正依頼 ①APIドキュメントを書く

Slide 18

Slide 18 text

弊社で過去に⾏われたAPIの繋ぎ込みの問題サーバエンジニアクライアントエンジニア × 徐々に更新しなくなる！

Slide 19

Slide 19 text

弊社で過去に⾏われたAPIの繋ぎ込みの問題サーバエンジニアクライアントエンジニア × 型や名前を⼿動で書くとミスする → パースエラーの原因に！ × 徐々に更新しなくなる！

Slide 20

Slide 20 text

弊社で過去に⾏われたAPIの繋ぎ込みの問題サーバエンジニアクライアントエンジニア × 型や名前を⼿動で書くとミスする → パースエラーの原因に！ × ⼝頭によるその場しのぎ対応が増えてドキュメントが置き去りに × 徐々に更新しなくなる！

Slide 21

Slide 21 text

これじゃ仲悪くなるよ・・・

Slide 22

Slide 22 text

No content

Slide 23

Slide 23 text

2. Swaggerについて

Slide 24

Slide 24 text

Swaggerとは？ REST APIを記述するための仕様と開発を後押しするツールを提供しているフレームワーク様々な団体がAPI記述のための標準フォーマットとして普及するよう推進している

Slide 25

Slide 25 text

Swaggerとは？ Googleトレンドでも伸びてきている！

Slide 26

Slide 26 text

Swaggerとは？弊社では3つのツールを利⽤している l Swagger Spec l Swagger UI l Swagger Codegen ଞʹ΋ͨ͘͞Μ͋ΔͷͰௐ΂ͯΈͯͶʂ 2.xܥ(stable)Λ ࢖ͬͯ·͢ʂ

Slide 27

Slide 27 text

Swagger Specとは？ YAML / JSON形式で記述できるAPIの設計図 [paths] エンドポイント, リクエスト, レスポンスの定義 [definitions] データ型の定義

Slide 28

Slide 28 text

Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義 API名

Slide 29

Slide 29 text

Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義 HTTP メソッド

Slide 30

Slide 30 text

Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義 APIの区分, タグ

Slide 31

Slide 31 text

Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義 APIの説明

Slide 32

Slide 32 text

Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義リクエスト / レスポンスのデータフォーマット

Slide 33

Slide 33 text

Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義リクエストパラメータ

Slide 34

Slide 34 text

Swagger Specとは？ [paths] エンドポイント, リクエスト, レスポンスの定義レスポンスパラメータ

Slide 35

Slide 35 text

Swagger Specとは？ [definitions] データ型の定義データ型の名前

Slide 36

Slide 36 text

Swagger Specとは？ [definitions] データ型の定義データ型の種類

Slide 37

Slide 37 text

Swagger Specとは？ [definitions] データ型の定義データ型の説明

Slide 38

Slide 38 text

Swagger Specとは？ [definitions] データ型の定義データ型の中⾝

Slide 39

Slide 39 text

Swagger Specとは？ [definitions] データ型の定義データ型の中⾝は複数指定もできる！

Slide 40

Slide 40 text

Swagger UIとは？ Swagger Specを基にした Web APIドキュメントを⽣成リクエスト / レスポンス定義を閲覧できるサンプルのレスポンスを返してくれるモック機能がある

Slide 41

Slide 41 text

Swagger UIとは？ http://petstore.swagger.io/?_ga=2.2822994 8.1082464866.1515850876- 167945699.1505133057

Slide 42

Slide 42 text

Swagger Codegenとは？ Swagger Specから様々な⾔語のクライアント / サーバのコードを⾃動⽣成してくれるなどなど…

Slide 43

Slide 43 text

Swagger Codegenとは？ Swagger Specから様々な⾔語のクライアント / サーバのコードを⾃動⽣成してくれる⾃動⽣成されるコードの雛形にはmustacheというテンプレートエンジンが使⽤されている

Slide 44

Slide 44 text

Swagger Codegenとは？ mustache（例 : C#のリクエストテンプレート） {{ hoge }} に Specのプロパティをマッピング

Slide 45

Slide 45 text

Swagger Codegenとは？コード⽣成結果例 (例 : C#のリクエストクラス) {{ hoge }} に Specのプロパティをマッピング

Slide 46

Slide 46 text

改善フローサーバエンジニアクライアントエンジニア ①Specを書く

Slide 47

Slide 47 text

改善フローサーバエンジニアクライアントエンジニア ②⾃動⽣成 ①Specを書く ②⾃動⽣成 ②⾃動⽣成

Slide 48

Slide 48 text

改善フローサーバエンジニアクライアントエンジニア ③~ API内容に更新や不備があればSpecを修正, 修正依頼 ②⾃動⽣成 ①Specを書く ②⾃動⽣成 ②⾃動⽣成

Slide 49

Slide 49 text

改善フローでのメリットサーバエンジニアクライアントエンジニア ○ 修正箇所が集約された！

Slide 50

Slide 50 text

改善フローでのメリットサーバエンジニアクライアントエンジニア ○ 修正箇所が集約された！ ○ ⾔語の違い以外は同じ定義のコードが⽣成される！

Slide 51

Slide 51 text

改善フローでのメリットサーバエンジニアクライアントエンジニア ○ ドキュメントもコードも置き去りにならない！ ○ 修正箇所が集約された！ ○ ⾔語の違い以外は同じ定義のコードが⽣成される！

Slide 52

Slide 52 text

少し仲良くなれそう！

Slide 53

Slide 53 text

3. グリフォンでの Swagger活⽤事例について

Slide 54

Slide 54 text

グリフォンでのSwagger活⽤開発フロー仕様書 / WFなどから作成するAPIの精査サーバ / クライアント間での認識合わせ API / リクエスト / レスポンス部分の実装サーバ / クライアントでの繋ぎ込み

Slide 55

Slide 55 text

グリフォンでのSwagger活⽤開発フロー 1. 仕様書 / WFなどから作成するAPIの精査 2. サーバ / クライアント間での認識合わせ仕様書とWF, Swagger UIを⾒ながらMTG サーバエンジニアがSwagger Specを記述

Slide 56

Slide 56 text

グリフォンでのSwagger活⽤開発フロー 3. API / リクエスト / レスポンス部分の実装 PHPとC#のリクエスト / レスンポンスクラス / 共通で使⽤するEnumを⾃動⽣成⾃動⽣成されるコードにサーバ /クライアントから要望があった使⽤するmustacheファイルを groovyスクリプトで切り替えながら⼀度に⾃動⽣成

Slide 57

Slide 57 text

例えばこんな要望があった型を厳密にするためにサーバで定義した型を使いたい！サーバエンジニア例えば・・・ CardLevel CardName ・初期化時必ずint型・1 ~ 100までの数値・初期化時必ずstring 型・10⽂字まで・空⽂字は認めない

Slide 58

Slide 58 text

Swaggerで扱えるデータ型

Slide 59

Slide 59 text

Specification Extensionを使ったデータ型拡張 Specification Extensionとは？ x- から始まるユーザ独⾃のプロパティ

Slide 60

Slide 60 text

Specification Extensionを使ったデータ型拡張 Specification Extensionとは？ x- から始まるユーザ独⾃のプロパティ

Slide 61

Slide 61 text

Specification Extensionを使ったデータ型拡張 Specification Extensionとは？ x- から始まるユーザ独⾃のプロパティ⾚枠 : x-serverType 緑枠 : x-serverNameSpaceList

Slide 62

Slide 62 text

Specification Extensionを使ったデータ型拡張サーバ定義のクラスは変換メソッドを定義したインタフェースを実装するようにしているレスポンス, リクエストクラス⽣成時に呼ばれて変換される仕組みに

Slide 63

Slide 63 text

Specification Extensionを使ったデータ型拡張リクエスト, レスポンスのフロークライアント Request 各機能コード Response 例: CardLevelを送って CardLevelを返してもらうだけ笑 ①intで送る

Slide 64

Slide 64 text

Specification Extensionを使ったデータ型拡張リクエスト, レスポンスのフロークライアント Request 各機能コード Response 例: CardLevelを送って CardLevelを返してもらうだけ笑 ①intで送る ② fromClientValueでサーバのクラスに変換

Slide 65

Slide 65 text

Specification Extensionを使ったデータ型拡張リクエスト受け付け時にフレームワークから呼ばれて各Controllerに渡される！

Slide 66

Slide 66 text

Specification Extensionを使ったデータ型拡張リクエスト, レスポンスのフロークライアント Request 各機能コード Response 例: CardLevelを送って CardLevelを返してもらうだけ笑 ①intで送る ② fromClientValueでサーバのクラスに変換 ③ 受け取ったサーバ定義クラスで処理を⾏う

Slide 67

Slide 67 text

Slide 68

Slide 68 text

Specification Extensionを使ったデータ型拡張レスポンス送信時にフレームワークから呼ばれた後、 JSONに変換されクライアントに渡される！

Slide 69

Slide 69 text

Slide 70

Slide 70 text

グリフォンでのSwagger活⽤開発フロー 4. サーバ / クライアントでの繋ぎ込み開発初期開発後 Swagger UIのモックAPI機能を使って早い段階から繋ぎこみをしながら開発 PHPサーバと繋ぎ込み

Slide 71

Slide 71 text

グリフォンでのSwagger活⽤開発フローサーバクライアント × 8 Swagger リポジトリ⾃動⽣成コード Submodule API定義記述

Slide 72

Slide 72 text

グリフォンでのSwagger活⽤開発フローサーバクライアント × 8 Swagger リポジトリ⾃動⽣成コード Submodule API定義記述 push

Slide 73

Slide 73 text

グリフォンでのSwagger活⽤開発フローサーバクライアント × 8 Swagger リポジトリ⾃動⽣成コード Submodule API定義記述 push 最新をpull APIモックをデプロイ⾃動⽣成コードを push

Slide 74

Slide 74 text

グリフォンでのSwagger活⽤開発フローサーバクライアント × 8 Swagger リポジトリ⾃動⽣成コード Submodule API定義記述 push 最新をpull APIモックをデプロイ⾃動⽣成コードを push 既存開発部分のAPIに修正が⼊るとコード修正まで上⼿く動かなくなるので複数バージョン環境を⽤意

Slide 75

Slide 75 text

グリフォンでのSwagger活⽤開発フローサーバクライアント × 8 Swagger リポジトリ⾃動⽣成コード Submodule API定義記述 push 最新をpull APIモックをデプロイ⾃動⽣成コードを push 接続先を開発フェーズで切り替えサーバ開発中

Slide 76

Slide 76 text

グリフォンでのSwagger活⽤開発フロー Unity上で簡単切り替え

Slide 77

Slide 77 text

グリフォンでのSwagger活⽤開発フローサーバクライアント × 8 Swagger リポジトリ⾃動⽣成コード Submodule API定義記述 push 最新をpull APIモックをデプロイ⾃動⽣成コードを push 接続先を開発フェーズで切り替えサーバ開発中サーバ開発後 PHPコードデプロイ

Slide 78

Slide 78 text

グリフォンでのSwagger活⽤開発フロー 4. サーバ / クライアントでの繋ぎ込み開発初期開発後 Swagger UIのモックAPI機能を使って早い段階から繋ぎこみをしながら開発 PHPサーバと繋ぎ込み疎通に使うリクエスト / レスポンス定義は同じなのでスムーズに繋ぎ込める！

Slide 79

Slide 79 text

仲良しに！

Slide 80

Slide 80 text

運⽤してみて気づいた点プロジェクトの規約ややりたいことに合わせたコード⽣成は少し敷居が⾼いかも改造するものがたくさん！ (mustache, codegen(java), ⽣成スクリプトなど) Swagger Specの記述, ファイル分割の規約はきちんと決めた⽅がいい何もしないとメンテ不能なyamlが簡単にできます！ (,,ﾟДﾟ)笑

Slide 81

Slide 81 text

グリフォンエンジニアブログもお願いします！ https://tech.griphone.co.jp/2017/1 0/08/swagger https://tech.griphone.co.jp/2017/1 0/08/swagger-mock-server

Slide 82

Slide 82 text

まとめ Swaggerを利⽤してAPI繋ぎこみのつらさを軽減する話をしました弊社のエンジニアブログもぜひ参照してみてください！ https://tech.griphone.co.jp グリフォンエンジニアブログで検索！

Slide 83

Slide 83 text

おしまいご清聴ありがとうございました！