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

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

1. 1. Swaggerで始める モデルファーストなAPI開発 NRIネットコム株式会社  佐々木拓郎 2015/11/21Developers.IO Meetup 番外編 ∼AWS モバイル/IoT サービス徹底攻略∼
2. 2. 佐々木拓郎 AWSとモバイルで 飯食ってます blog: http://blog.takuros.net twitter: @dkfj 自己紹介
3. 3. ちょっと宣伝 Amazon Web Services パターン別構築・運用ガイド 一番大切な知識と技術が身につく http://amzn.to/1BLiYcO AWSの一番分厚い本 （大容量480ページ）
4. 4. 序文に書いた言葉
5. 5. もうちょっと宣伝 WEB+DB PRESS Vol.88 モバイル開発最前線 ―― ビルドもテストもデプロイも クラウドで加速! http://amzn.to/1QhqBl7 DeviceFarmの話も少し載せています
6. 6. まだまだ宣伝 Rubyによるクローラー開発技法 巡回・解析機能の実装と21の運用例 http://amzn.to/1lsJ5id 2014年 ジュンク堂書店  コンピュータ書 年間総合ランキング14位
7. 7. Web周りのビジネスを専門としている会社 • Webシステムの企画・設計・開発・運用 • 24時間365日の運用体制 • デザインを重視し、ディレクター／デザイナーが多数在籍 • スマホ／タブレットも得意 • AWSをはじめとするクラウドにも力を入れている • 最近のトレンドは、デジタルマーケティング NRIネットコム
8. 8. こんな会社です 新しいもの好き 2015年6月 Pepper部長 入社
9. 9. たまに頭を抱えています
10. 10. NAOもいます
11. 11. Swaggerで始める モデルファーストなAPI開発
12. 12. アンケート JSON or YAMLを読める人？ JSON or YAMLを書ける人？ Swaggerを知ってる人？ Swaggerを使ってる人？ CloudFormationのテンプレートを書くのが好きだ！！
13. 13. 今日の目的 家に帰ったらSwaggerを 触ってみたくなる
14. 14. Swaggerとは？
15. 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. 16. Open API Initiative RESTful APIの記述標準化を目指す「Open API Initiative」を マイクロソフト、Google、IBMらが立ち上げ。 Swaggerをベースに - Publickey http://www.publickey1.jp/blog/15/open_api_initiative.html
17. 17. Swaggerは、REST APIの記述に関する仕様と それに関連するツール それでは、REST APIとは？
18. 18. REST API Representational State Transfer 狭義のREST（RESTful） RESTの定義を満たしたREST（実は余りない） ステートレスなクライアント/サーバプロトコル リソース指向 URIによるリソースの識別 HTTPメソッドを利用した操作 広義のREST（Web API） XMLやJSONで応答（XML/JSON over HTTP） RESTと称しているものの多くがこっち
19. 19. RESTのベストプラクティス 幾つもあるので、そのごく一部を紹介 動詞ではなく名詞を使う 悪い例 /getProducts /listOrders 良い例 GET /products : すべての製品のリストを返す POST /products : コレクションに製品を加える GET /products/4 : 4番の製品を取り出す PATCH/PUT /products/4 : 4番の製品を更新する
20. 20. お勧め書籍 Web API: The Good Parts 内容が平易で読みやすい
21. 21. Swaggerの構造
22. 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. 23. Swaggerの概念図 サーバクライアント API JSON Swagger UI ドキュメント／UI 生成 Swagger Spec FileSwagger Editor 編集 APIコール 生成 API 生成 Swagger Core
24. 24. Swagger Editor
25. 25. Swagger UI
26. 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. 27. Swagger UIとEditorの デモ http://petstore.swagger.io/ http://editor.swagger.io/
28. 28. Swagger Spec作成のアプローチ Swagger Specをどうやって作るのか？ モデルありき モデルを元に生成する Swagger EditorでSwaggerの定義を作成 Swagger Specファイル作成 実装ありき 既に実装済みのREST APIが存在 実装からモデルを抽出 Swagger Specファイル作成
29. 29. RESTを利用する時に Swaggerを使うと 何が解決されるのか？
30. 30. インターフェース（API）の設計書 例）Amazon S3のREST APIのリファレンス
31. 31. APIドキュメントのよくある課題 API Documentの陳腐化。最新のコードに追随できない Excellの設計書 フォーマットの統一がやりやすい バージョン管理で差分が解りづらい 開くの面倒くさい。。。 Wiki 手軽に編集／閲覧できる フォーマットの統一が難しい コードのバージョン管理と紐付けが出来ない
32. 32. コードとドキュメントを一緒に管理 コードとドキュメントを、一緒にバージョン管理すれば いいじゃない。Swaggerなら簡単に扱いやすい
33. 33. ドキュメントと生成物の乖離の問題 バージョン管理だけでは、生成物との同一性が保証できない テストが必要 APIドキュメントからテストすればいいじゃない。 SwaggerならドキュメントからAPIのテストも実行できる Vモデル
34. 34. SwaggerによるAPIの動作テスト Swagger UI レスポンス
35. 35. これに似ている Create Table members ( member_id beignet NOT NULL AUTO_INCREMENT, email_address varchar(255) NOT NULL, password varchar(64) ); Excelのテーブル定義からポチッとなでDDL生成 DDL発行
36. 36. Swagger関連ツールの 導入
37. 37. Swagger Editorのインストール Node.js前提 ソースのダウンロードして、httpサーバとして起動 $ git clone https://github.com/swagger-api/swagger-editor.git $ cd swagger-editor $ npm start
38. 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. 39. API Gateway ✕ Swagger
40. 40. API Gatewayとは？ AWSやインターネット上のサービスに対し てREST APIを提供するサービス ４つの機能 Lambda連携 HTTP Proxy AWS Proxy Mock機能 マネージド・サービス スケーラブル （ユーザは）メンテナンスフリー
41. 41. API Gatewayは、素晴らしいサービス 工夫次第で、いろいろ活用できる ただし、UIからの設定が面倒くさい
42. 42. API Gatewayの設定デモ（モック機能編） 設定項目が多く、やってられん！！ そんな貴方に朗報が！！
43. 43. AWS API Gateway Importer AWS謹製のAPI Gatewayの設定インポートツール AWS CLIツールを利用してSwagger Specを元に API Gatewayを作成 実体は、Java Java 1.8以上 要Maven Importer Swagger Spec
44. 44. AWS API Gateway Importerによる API Gateway作成のデモ
45. 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. 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. 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. 48. 作成されたAPI Gatewayの確認 AWS Consleで確認 新規で作成されている
49. 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. 50. 疑問 Updateの適切な使い方 依存関係で死ぬことがある 原子性 (ATOMICITY)が保証されていないっぽい ステージを別けて利用する？  バージョンで管理したい  Blue-Green Deployしたい
51. 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. 52. API作成の流れ with Swagger 1. Swagger EditorでSpecを書く 2. AWS API Gateway Importerでインポート 3. SpecのHost名を書き換え  （DNSのCName設定の方がスマート？） 4. Swagger UIでテストしてみる あまりスマートではないので、CLIと組み合わせ？
53. 53. POSTメソッドのテスト Chrome拡張のPostmanというツールもあるよ https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop
54. 54. Swaggerを使ってみた感想 最初の取っ付きにくさ、最強 機能が多すぎて、何を使ってよいか解らない 環境面の用意が面倒くさい ドキュメント化のUIやエディタは便利 アノテーションは、たぶん使わない Electronで、ディスクトップアプリ化してみようか？
55. 55. 何故、API化するのか？
56. 56. ５年前に作ったとあるサービス http://www.nri-net.com/mobileconf/ https://www.youtube.com/watch?v=7Rk2pL3PAXc
57. 57. 疎結合なシステム Webサーバ データベース サーバ（会議システム） 参照ページの通知 初回ダウンロード 参照ページの同期 サーバ・アプリ間は、APIを通じてのやり取り クライアント（iPad） API
58. 58. クライアントの追加 http://nri-net.com/company/news/20151119.html
59. 59. 疎結合なシステム Webサーバ データベース サーバ（会議システム） 参照ページの通知 初回ダウンロード 参照ページの同期 サーバ側は、何も手を加えなくても良い クライアント（iPad） API クライアント（Windows） 追加
60. 60. ちなみにサーバ部分を API Gateway + Lambda + DynamoDB に置き換えたら、 1日で出来ちゃったのは内緒
61. 61. アーキテクチャ例 DynamoDB S3 API Gateway Lambda ページ番号の 参照・保存 資料の ダウンロード WebSocketで ページ同期 ページの通知 各種APIの呼び出し
62. 62. 今日の目的 家に帰ったらSwaggerを 触ってみたくなった？
63. 63. ご静聴、ありがとうございました。