開発効率を上げるSwaggerの話

by ykagano

Slide 1

Slide 1 text

開発効率を上げる Swaggerの話 @ykagano

Slide 2

Slide 2 text

1 ■⾦融系のエンジニアです • SIerの会社：電⼦マネーシステムの受託開発 • 電⼦マネーの会社： Web／スマホアプリ開発・企画 • Web系の会社：決済関連のWeb開発イマココ加賀野祐@ykagano

Slide 3

Slide 3 text

開発効率を上げる Swaggerの話 1. はじめに 2. まず動かしてみる 3. Swagger YAMLを⾒る 4. APIモックを作る 5. さいごに 2

Slide 4

Slide 4 text

突然ですが開発に疲れてませんか？ 3

Slide 5

Slide 5 text

Swaggerを使うとこれだけ楽になります 4 ・REST APIの仕様を⾒るのが楽・REST APIの実⾏ツールを作るのが楽・REST APIの仕様を書くのが楽・REST APIのモックを作るのが楽

Slide 6

Slide 6 text

ということを聞いて⾊々調べたのでここで発表します 5 内容が間違っていたらあとでこっそり教えてください

Slide 7

Slide 7 text

開発効率を上げる Swaggerの話 1. はじめに 2. まず動かしてみる 3. Swagger YAMLを⾒る 4. APIモックを作る 5. さいごに 6

Slide 8

Slide 8 text

Swagger-Editorというオンラインツールを使います 7 まず動かしてみる http://editor.swagger.io/ ※httpsは標準のサンプルがクロスドメインで動かなかった

Slide 9

Slide 9 text

8 左のウィンドウにyaml形式でAPIの仕様を書くと右のウィンドウに仕様書がリアルタイムで反映されます

Slide 10

Slide 10 text

書き上がったら「Generate Server」から⽣成するサーバーアプリケーションを選択しますここではサクッと動かすため「nodejs-server」を選択します 9

Slide 11

Slide 11 text

ダウンロードしたzipを解凍して Terminalから解凍したフォルダ内に移動します 10 サーバーが起動しました

Slide 12

Slide 12 text

11 http://localhost:8080/docs をブラウザで開く仕様書が⾒える

Slide 13

Slide 13 text

12 APIが叩ける

Slide 14

Slide 14 text

元々サンプルとして⽤意されている 13 http://petstore.swagger.io/v2/pet/1 をローカルサーバーから叩いています http://petstore.swagger.io/ を開くとサンプルAPIの仕様書が⾒れます

Slide 15

Slide 15 text

14 ・REST APIの仕様を⾒るのが楽 ✅ ・REST APIの実⾏ツールを作るのが楽 ✅ ・REST APIの仕様を書くのが楽・REST APIのモックを作るのが楽ここまでで2つクリア

Slide 16

Slide 16 text

開発効率を上げる Swaggerの話 1. はじめに 2. まず動かしてみる 3. Swagger YAMLを⾒る 4. APIモックを作る 5. さいごに 15

Slide 17

Slide 17 text

16 1. メタデータとサーバー情報の記述 2. エンドポイントの記述 3. モデル定義の記述サンプルを削ったので⾒ていきます yamlにはざっくりこの３点を書きます

Slide 18

Slide 18 text

17 1. メタデータとサーバー情報の記述

Slide 19

Slide 19 text

18 2. エンドポイントの記述

Slide 20

Slide 20 text

19 3. モデル定義の記述

Slide 21

Slide 21 text

20 ほら簡単でしょ？

Slide 22

Slide 22 text

21 ・REST APIの仕様を⾒るのが楽 ✅ ・REST APIの実⾏ツールを作るのが楽 ✅ ・REST APIの仕様を書くのが楽 ✅ ・REST APIのモックを作るのが楽ここまでで3つクリア

Slide 23

Slide 23 text

開発効率を上げる Swaggerの話 1. はじめに 2. まず動かしてみる 3. Swagger YAMLを⾒る 4. APIモックを作る 5. さいごに 22

Slide 24

Slide 24 text

突然ですがオンラインツールだとセキュリティに不安がありませんか？ 23

Slide 25

Slide 25 text

当たり前ですがオフライン版もあります 24 公式 https://swagger.io/swagger-editor/ ソース https://github.com/swagger-api/swagger-editor

Slide 26

Slide 26 text

Editorをインストールして起動します 25 // git cloneだと重かったので、配布URLからzipでwget $ wget https://codeload.github.com/swagger-api/swagger-editor/zip/master $ unzip master $ cd swagger-editor-master $ npm install $ npm start あとはオンラインエディタと使い⽅は同じです

Slide 27

Slide 27 text

26 ホスト名を書かなければlocalhostが APIサーバーになります

Slide 28

Slide 28 text

27 APIを叩くと常に同じレスポンスが返ります

Slide 29

Slide 29 text

28 レスポンスを変えるには yamlでexampleを指定するか seviceフォルダのjsを直接編集します

Slide 30

Slide 30 text

29 ・REST APIの仕様を⾒るのが楽 ✅ ・REST APIの実⾏ツールを作るのが楽 ✅ ・REST APIの仕様を書くのが楽 ✅ ・REST APIのモックを作るのが楽 ✅ これで全部クリア

Slide 31

Slide 31 text

開発効率を上げる Swaggerの話 1. はじめに 2. まず動かしてみる 3. Swagger YAMLを⾒る 4. APIモックを作る 5. さいごに 30

Slide 32

Slide 32 text

今⽇の話はあくまで基本的な使い⽅です REST APIのソースコードにアノテーションを記述して・ソース＝ドキュメント・ソース＝実⾏ツールにしたりもできる（らしいそれでは 31