参考
こちらの動画を参考にやってみる。
SwaggerHub を使うことで以下のことができるようになるのがよさそう
- Amazon API Gateway が作成できる
- AWS Lambda も作成できる
- 最終的にはドキュメントが作成されている
- ドキュメントから API を実行できるので動作も確認できちゃう
学習の目的・モチベーション
- 普段はインフラエンジニアなので、個人的になにかプログラミングしてもしばらく触らないと何を書いてたのかよくわからなくなる。なのでドキュメントも一緒に作れたら最高なんじゃないか
- Swagger + Amazon API Gateway & Lambda の良さを確認
- Serverless Framework とどっちが使い勝手良さそうか
- 何も作ってみるか
- cloudsearch 上に登録してあるアイテムを検索する
- だいたいこんな感じで
- 全件
- GET https:/(url)/v1/items/
- カテゴリに一致するアイテム
- GET https:/(url)/v1/items/{category}/
- 1アイテム
- GET https:/(url)/v1/items/{category}/{itemid}
- 全件
- 今回は v1/items/ だけとりあえず作ってみる
id | name | category |
---|---|---|
1 | item1 | [shoes, sports, running] |
2 | item2 | [fasion, shoes] |
3 | item3 | [food, meat] |
4 | item4 | [food, fish] |
前提
- AWSアカウント
- IAM作成する権限持っている
- Lambda作成する権限
- Cloudsearch作成する権限
- SwaggerHub
- アカウント作成済み
- さっとSwaggerHubの動画は見た
(復習)HTTPメソッド
RFC 7231 - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
https://tools.ietf.org/html/rfc7231#section-4.3
Method | 説明 |
---|---|
GET | リソースの取得 |
HEAD | メタ情報の取得 |
POST | リソースの作成 |
PUT | リソースの更新 |
DELETE | リソースの削除 |
CONNECT | クライアントとサーバ間にトンネルを確立 |
OPTIONS | サーバがサポートしているメソッドを応答 |
TRACE | 動作をトレース |
Swaggerはどう書けばいいか
http://swagger.io/specification/#pathsObject
http://swagger.io/specification/#pathItemObject
マニュアルにしっかりかいてある。
新しい言語を覚えるよりはコストはかからないけど、たくさんかける分それなりのコストはあるような気はする。
SwaggerHub上でAPIを新規作成
Create a New API
をクリック
Name, Version, Title, Description, Visibility を設定して
Create API
をクリック
小さく書いてこんな感じ
swagger: '2.0'
info:
version: 0.0.1
title: test shop api
description: test shop api
basePath: /v1
paths:
/items:
get:
responses:
200:
description: ok
404:
description: item not found
405:
description: invalid input
API Gateway を作成してみる
IAM ユーザー
swaggerHub から AWS を操作するために
* ユーザー swaggerhub-user を作成する
* Policy を付与しておく
* AmazonAPIGatewayAdministrator
* AWSLambdaFullAccess
* ロール swaggerhub-lambda を作成しておく
* Policy を付与しておく
* AWSLambdaFullAccess
* ARN をメモしておく
SwaggerHub 設定 (Manage Integrations)
Manage Integrations
をクリック
+
をクリック
Amazon API Gateway Lamdba Sync
を選んで Add
をクリック
よしなに設定する。
Execution role for creating non-existing Lambda Functions
には ロール swagger-lambda の ARN を入力する。
Create
Save
設定を確認する(一部設定を保存する作業アリ)
API Gateway の設定を見ると、 itemsGET
Lamdba function をキックするようになっている。
Integration Request
をクリック
Lambda Function
の鉛筆マークをクリック
OK
ボタンをクリック
Lambda function はこんなかんじ
API Gateway で動作確認をする
TEST
をクリック
TEST
ボタンをクリック
Lambda function からメッセージが返ってくる
感想
今のところ Serverless Framework がしっくりきているので
偏った意見かもしれません。
- ドキュメントが作れちゃって、なおかつそのドキュメントから実行できちゃう(らしい。hostを設定するっぽい)のはいい感じ
- サーバーレス、って考えると、他のリソース(S3とかDynamoDBとか)も cloudformation のファイルで一緒に作れるServerless Framework のほうがいい感じがする
- Private だと有料
- API Gateway の Stage, Lambda の Alias で dev,stg,pro を管理したいけどできるのか?
- Serverless Framework はそこら辺も簡単だった
- 修正するときのデプロイの流れがイメージ出来ない
- Serverless Framework はcapistrano の task に追加しやすそうなイメージ
-
sls dash summary
でとりあえず頑張るけど Serverless Framework から swagger に(なにかを)とりこんでドキュメントができればいいなぁ