(レポート) AWSモバイル/IoTサービス徹底攻略！！ 「Swaggerで始めるモデルファーストなAPI開発」#cmdevio

森永です。
11/21（土）に目黒のAWSJにて開催された「AWSモバイル/IoTサービス徹底攻略！！〜Developers.IO Meetup番外編〜」のレポートです！

イベント概要

本勉強会は、基本的な内容のBasic Track、応用的な内容のAdvanced Track、実際に試すことの出来るHands Onの3トラックに分けてAWSのモバイルサービスや、サーバーレスアーキテクチャ、IoTのお話をするというものです。

セッション内容

NRIネットコム（株）佐々木 拓郎さん

[slideshare id=55359338&doc=classmethodswagger-151121063232-lva1-app6892]

自己紹介

Amazon Web Servicesパターン別構築・運用ガイドを執筆
AWS関連で一番分厚い本
本の中にクラウドネイティブという名のもとに、クラウドを前提としたアーキテクチャ・設計が来るんじゃないかなということを書かれていた
思ったより早くクラウドネイティブの波が来たので、今クラウドネイティブ特化した本を執筆中

WEB+DB PRESS Vol.88にも寄稿

NRIネットコム

NRIのグループ会社
WEB周りのビジネスを専門としている
ディレクターやデザイナーが沢山
最近のトレンドはデジタルマーケティング
新しいもの好きなので、PepperくんやNAOがいますよ

アンケート

• JSON or YAML読める人？
• JSON or YAML書ける人？
• Swaggerを知ってる人？
• Swaggerを使ってる人？
• CloudFormationのJSON書くの好きな人？

目標は家に帰ってSwagger使ってみようかなと思ってもらうこと

Swaggerとは

人とコンピュータに優しいREST APIの記述についての仕様とそれに関するツール
もともと製品などではない

そもそもREST APIとは

• 狭義のREST（RESTful）←あんまり存在してない
  • RESTの定義を満たしたREST
    • ステートレスなクライアント/サーバプロトコル
    • リソース指向
    • URIによるリソースの識別
    • HTTPメソッドを利用した操作
• 広義のREST
  • HTTPメソッドを利用した操作がある

RESTのベストプラクティス

• 動詞でなくて名刺を使う
  • 悪い例
    • /getProducts
    • /listOrders
  • いい例
    • GET /products
    • POST /products
    • GET /products/4 みたいな感じ

オススメの書籍はオライリーのWeb API The good parts

Swagger関連用語

これを覚えておくといいです

• Swagger Spec: Swaggerの仕様に準じたドキュメント
• Swagger Core: Swagger specを生成するためのライブラリ
• Swagger Codegen: JSONからクライアントコード生成
• SWagger UI:よく使う。JSONからドキュメントを作ってくれる
• Swagger Editor:よく使う。ブラウザ上でJSON編集できる

デモ

Swagger Editorのデモサイトはこちら
Swagger UIのデモサイトはこちら

Swagger Spec作成のアプローチ

どうやって作るのか

• モデルありき→設計書作ってそれを元に作成
• 実装ありき→実装してあるものからモデルを抽出して作成
  • アノテーションのようなもので自動生成

RESTを利用するときにSwagger使うと何が解決されるのか

• インターフェース（API）のドキュメント
  • 問題点
    • ドキュメントの陳腐化
    • Excellの設計書だとフォーマット統一は簡単だが、バージョン管理きつい
    • Wikiだと編集／閲覧は楽だが、フォーマット統一、コードのバージョンと紐付けが厳しい
      • コードとドキュメントは一緒に管理するのが一番
      • Swaggerだとコードとドキュメントを一緒にバージョン管理しやすい
    • ドキュメントと生成物が乖離してしまう問題がある
      • APIドキュメントからテスト生成すればいい
      • Swaggerならテストを作成できる

Excelのテーブル定義からDDL生成となんだか似てる 設計書からコードの自動生成はどうかと思うが、定義の生成はやるべき

インストール

Swagger EditorはNode.js前提
Swagger UIはNode.jsとgulp前提

AWSとSwaggerの関係

API Gatewayは素晴らしいサービスだが、UIからの設定が面倒
ブラウザから全部やると絶対失敗する
→ここでSwaggerを使って解決

「AWS API Gateway Importer」というAPI Gatewayの設定インポートツール
Swagger Specを取り込むとAPI Gatewayの設定を行ってくれる
JavaやMavenが必要です

AWS API Gateway Importerのデモ

関係ないけど便利ツール

POSTメソッドのテストするためのツール
Postmanというchrome拡張

まとめ

• とっつきにくさ、最強
• 環境用意が面倒
• ドキュメント化やUIやエディタはすごい便利
• 全部の機能を使う必要はない。必要な物だけ使いましょう
• ブラウザアプリはちょっと面倒、アプリにしてほしいな

さいごに

私自身、API Gatewayをブラウザから設定するのが大変だなと感じていました。
セッションを聞いて夢が広がりました。

家帰ったらSwagger使ってみまーす。