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

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

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

イベント概要

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

セッション内容

IMGP2032

NRIネットコム(株)佐々木 拓郎さん


自己紹介

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使ってみまーす。