1. Swaggerで始める
モデルファーストなAPI開発
NRIネットコム株式会社
佐々木拓郎
2015/11/21Developers.IO Meetup 番外編
∼AWS モバイル/IoT サービス徹底攻略∼

2. 佐々木拓郎
AWSとモバイルで
飯食ってます
blog: http://blog.takuros.net
twitter: @dkfj
自己紹介

3. ちょっと宣伝
Amazon Web Services
パターン別構築・運用ガイド
一番大切な知識と技術が身につく
http://amzn.to/1BLiYcO
AWSの一番分厚い本
（大容量480ページ）

4. 序文に書いた言葉

5. もうちょっと宣伝
WEB+DB PRESS Vol.88
モバイル開発最前線 ――
ビルドもテストもデプロイも
クラウドで加速!
http://amzn.to/1QhqBl7
DeviceFarmの話も少し載せています

6. まだまだ宣伝
Rubyによるクローラー開発技法
巡回・解析機能の実装と21の運用例
http://amzn.to/1lsJ5id
2014年 ジュンク堂書店
コンピュータ書 年間総合ランキング14位

7. Web周りのビジネスを専門としている会社
• Webシステムの企画・設計・開発・運用
• 24時間365日の運用体制
• デザインを重視し、ディレクター／デザイナーが多数在籍
• スマホ／タブレットも得意
• AWSをはじめとするクラウドにも力を入れている
• 最近のトレンドは、デジタルマーケティング
NRIネットコム

8. こんな会社です
新しいもの好き
2015年6月
Pepper部長
入社

9. たまに頭を抱えています

10. NAOもいます

11. Swaggerで始める
モデルファーストなAPI開発

12. アンケート
JSON or YAMLを読める人？
JSON or YAMLを書ける人？
Swaggerを知ってる人？
Swaggerを使ってる人？
CloudFormationのテンプレートを書くのが好きだ！！

13. 今日の目的
家に帰ったらSwaggerを
触ってみたくなる

14. Swaggerとは？

15. Swagger
What is Swagger?
The goal of Swagger™ is to define a standard, language-agnostic interface to
REST APIs which allows both humans and computers to discover and
understand the capabilities of the service without access to source code,
documentation, or through network traffic inspection. When properly defined
via Swagger, a consumer can understand and interact with the remote service
with a minimal amount of implementation logic. Similar to what interfaces have
done for lower-level programming, Swagger removes the guesswork in calling
the service.
人とコンピュータに優しい
REST APIを記述する標準仕様
（を目指してます）
http://swagger.io/getting-started/

16. Open API Initiative
RESTful APIの記述標準化を目指す「Open API Initiative」を
マイクロソフト、Google、IBMらが立ち上げ。
Swaggerをベースに - Publickey
http://www.publickey1.jp/blog/15/open_api_initiative.html

17. Swaggerは、REST APIの記述に関する仕様と
それに関連するツール
それでは、REST APIとは？

18. REST API
Representational State Transfer
狭義のREST（RESTful）
RESTの定義を満たしたREST（実は余りない）
ステートレスなクライアント/サーバプロトコル
リソース指向
URIによるリソースの識別
HTTPメソッドを利用した操作
広義のREST（Web API）
XMLやJSONで応答（XML/JSON over HTTP）
RESTと称しているものの多くがこっち

19. RESTのベストプラクティス
幾つもあるので、そのごく一部を紹介
動詞ではなく名詞を使う
悪い例
/getProducts
/listOrders
良い例
GET /products : すべての製品のリストを返す
POST /products : コレクションに製品を加える
GET /products/4 : 4番の製品を取り出す
PATCH/PUT /products/4 : 4番の製品を更新する

20. お勧め書籍
Web API: The Good Parts
内容が平易で読みやすい

21. Swaggerの構造

22. Swagger関連の用語（の一部）
Tool Description
Swagger Spec
REST APIに対して
Swaggerの仕様に準じたドキュメント
Swagger Core
REST APIの実装から
Swagger specを生成するためのライブラリ
Swagger Codegen
コマンドラインツール
Swagger JSONからクライアントコード生成
Swagger UI
SWagger 準拠 API （Swagger SPec）から
動的にドキュメントを生成するツール
Swagger Editor
ブラウザ上で動くJSON/YAMLのエディタ
リアルタイムで構文チェック

23. Swaggerの概念図
サーバクライアント
API
JSON
Swagger UI
ドキュメント／UI
生成
Swagger Spec FileSwagger Editor
編集
APIコール
生成
API 生成
Swagger Core

24. Swagger Editor

25. Swagger UI

26. Swagger Spec
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Swagger Petstore",
"description": "A sample API that uses a petstore as an example
to demonstrate features in the swagger-2.0 specification",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"name": "Swagger API Team"
},
"license": {
"name": "MIT"
}
},
"host": "petstore.swagger.io",
"basePath": "/api",
"schemes": [
"http"
],
"consumes": [
JSONで記述

27. Swagger UIとEditorの
デモ
http://petstore.swagger.io/
http://editor.swagger.io/

28. Swagger Spec作成のアプローチ
Swagger Specをどうやって作るのか？
モデルありき
モデルを元に生成する
Swagger EditorでSwaggerの定義を作成
Swagger Specファイル作成
実装ありき
既に実装済みのREST APIが存在
実装からモデルを抽出
Swagger Specファイル作成

29. RESTを利用する時に
Swaggerを使うと
何が解決されるのか？

30. インターフェース（API）の設計書
例）Amazon S3のREST APIのリファレンス

31. APIドキュメントのよくある課題
API Documentの陳腐化。最新のコードに追随できない
Excellの設計書
フォーマットの統一がやりやすい
バージョン管理で差分が解りづらい
開くの面倒くさい。。。
Wiki
手軽に編集／閲覧できる
フォーマットの統一が難しい
コードのバージョン管理と紐付けが出来ない

32. コードとドキュメントを一緒に管理
コードとドキュメントを、一緒にバージョン管理すれば
いいじゃない。Swaggerなら簡単に扱いやすい

33. ドキュメントと生成物の乖離の問題
バージョン管理だけでは、生成物との同一性が保証できない
テストが必要
APIドキュメントからテストすればいいじゃない。
SwaggerならドキュメントからAPIのテストも実行できる
Vモデル

34. SwaggerによるAPIの動作テスト
Swagger UI
レスポンス

35. これに似ている
Create Table members (
member_id beignet NOT NULL AUTO_INCREMENT,
email_address varchar(255) NOT NULL,
password varchar(64)
);
Excelのテーブル定義からポチッとなでDDL生成
DDL発行

36. Swagger関連ツールの
導入

37. Swagger Editorのインストール
Node.js前提
ソースのダウンロードして、httpサーバとして起動
$ git clone https://github.com/swagger-api/swagger-editor.git
$ cd swagger-editor
$ npm start

38. Swagger UIのインストール
Node.js前提、gulpも必要
ビルドして、./dist/index.htmlをブラウザでオープン
$ git clone https://github.com/swagger-api/swagger-ui.git
$ cd swagger-ui
$ npm install
$ gulp

39. API Gateway ✕ Swagger

40. API Gatewayとは？
AWSやインターネット上のサービスに対し
てREST APIを提供するサービス
４つの機能
Lambda連携
HTTP Proxy
AWS Proxy
Mock機能
マネージド・サービス
スケーラブル
（ユーザは）メンテナンスフリー

41. API Gatewayは、素晴らしいサービス
工夫次第で、いろいろ活用できる
ただし、UIからの設定が面倒くさい

42. API Gatewayの設定デモ（モック機能編）
設定項目が多く、やってられん！！
そんな貴方に朗報が！！

43. AWS API Gateway Importer
AWS謹製のAPI Gatewayの設定インポートツール
AWS CLIツールを利用してSwagger Specを元に
API Gatewayを作成
実体は、Java
Java 1.8以上
要Maven
Importer
Swagger Spec

44. AWS API Gateway Importerによる
API Gateway作成のデモ

45. Macの場合
必要ツールのインストール
ビルド
API Gateway Importerのインストール
$ brew install Caskroom/cask/java
$ brew install maven
$ git clone https://github.com/awslabs/aws-apigateway-swagger-
importer.git
$ cd aws-apigateway-swagger-importer/
$ mvn assembly:assembly

46. インストール後の稼働テスト
$ ./aws-api-import.sh
$ ./aws-api-import.sh
Usage: aws-api-import [options] Path to API definition file to
import
Options:
--create, -c
Create a new API
Default: false
--deploy, -d
Stage used to deploy the API
--help
Default: false
--profile, -p
AWS CLI profile to use
Default: default
--raml-config
Provide a configuration file to load AWS information from
--test, -t
Delete the API after import (create only)
Default: false
--update, -u

47. API Gatewayの作成
$ ls tst/resources/swagger/
apigateway.json petstore-with-external-docs.json
basic.json petstore.json
large.json test.json
petstore-expanded.json uber.json
petstore-minimal.json uber.yaml
petstore-simple.json
用意されているテンプレートを利用
実行
$ ./aws-api-import.sh -c tst/resources/swagger/petstore-simple.json
2015-11-21 07:42:29,295 INFO - Skip unsupported property name
region in profile [default].
2015-11-21 07:42:29,297 INFO - Skip unsupported property name
region in profile [dev].
2015-11-21 07:42:32,823 INFO - Attempting to create API from
Swagger definition. Swagger file: tst/resources/swagger/petstore-
simple.json

48. 作成されたAPI Gatewayの確認
AWS Consleで確認
新規で作成されている

49. 更新
API_IDを元に更新できる
https://console.aws.amazon.com/apigateway/home?
region=us-east-1#/restapis/ue6wiba5e7/
これがID
コマンド
./aws-api-import.sh --update API_ID --deploy
STAGE_NAME path/to/swagger.yaml

50. 疑問
Updateの適切な使い方
依存関係で死ぬことがある
原子性 (ATOMICITY)が保証されていないっぽい
ステージを別けて利用する？
バージョンで管理したい
Blue-Green Deployしたい

51. 参考情報
API GatewayのCLIが利用可能
o create-api-key
o create-base-path-mapping
o create-deployment
o create-domain-name
o create-model
o create-resource
o create-rest-api
o create-stage
o delete-api-key
o delete-base-path-mapping
o delete-client-certificate
o delete-deployment
o delete-domain-name
o delete-integration
o delete-integration-response
o delete-method
o delete-method-response
o delete-model
o delete-resource
o delete-rest-api
o delete-stage
o flush-stage-cache
o generate-client-certificate
o get-account
o get-api-key
o get-api-keys
o get-base-path-mapping
o get-base-path-mappings
o get-client-certificate
o get-client-certificates
o get-deployment
o get-deployments
o get-domain-name
o get-domain-names
o get-integration
o get-integration-response
o get-method
o get-method-response
o get-model
o get-model-template
o get-models
o get-resource
o get-resources
o get-rest-api
o get-rest-apis
o get-sdk
o get-stage
o get-stages
o help
o put-integration
o put-integration-response
o put-method
o put-method-response
o test-invoke-method
o update-account
o update-api-key
o update-base-path-mapping
o update-client-certificate
o update-deployment
o update-domain-name
o update-integration
o update-integration-response
o update-method
o update-method-response
o update-model
o update-resource
o update-rest-api
o update-stage

52. API作成の流れ with Swagger
1. Swagger EditorでSpecを書く
2. AWS API Gateway Importerでインポート
3. SpecのHost名を書き換え
（DNSのCName設定の方がスマート？）
4. Swagger UIでテストしてみる
あまりスマートではないので、CLIと組み合わせ？

53. POSTメソッドのテスト
Chrome拡張のPostmanというツールもあるよ
https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop

54. Swaggerを使ってみた感想
最初の取っ付きにくさ、最強
機能が多すぎて、何を使ってよいか解らない
環境面の用意が面倒くさい
ドキュメント化のUIやエディタは便利
アノテーションは、たぶん使わない
Electronで、ディスクトップアプリ化してみようか？

55. 何故、API化するのか？

56. ５年前に作ったとあるサービス
http://www.nri-net.com/mobileconf/
https://www.youtube.com/watch?v=7Rk2pL3PAXc

57. 疎結合なシステム
Webサーバ データベース
サーバ（会議システム）
参照ページの通知
初回ダウンロード
参照ページの同期
サーバ・アプリ間は、APIを通じてのやり取り
クライアント（iPad）
API

58. クライアントの追加
http://nri-net.com/company/news/20151119.html

59. 疎結合なシステム
Webサーバ データベース
サーバ（会議システム）
参照ページの通知
初回ダウンロード
参照ページの同期
サーバ側は、何も手を加えなくても良い
クライアント（iPad）
API
クライアント（Windows）
追加

60. ちなみにサーバ部分を
API Gateway + Lambda + DynamoDB
に置き換えたら、
1日で出来ちゃったのは内緒

61. アーキテクチャ例
DynamoDB
S3
API Gateway
Lambda
ページ番号の
参照・保存
資料の
ダウンロード
WebSocketで
ページ同期
ページの通知
各種APIの呼び出し

62. 今日の目的
家に帰ったらSwaggerを
触ってみたくなった？

63. ご静聴、ありがとうございました。