API Gateway を使う際、だんだんAPIの数が増えてくる（リソース・メソッドが増えてくる）と、コンソールで定義するのが大変になってきます。 特に、APIのリネームなんてことが起こったら、嫌になってきます。
なので、それを避けるために、API定義を Swagger で記述して、それを API Gateway にインポートさせて API 定義を簡単に行えるようにしています。
※ Swagger とは、APIを記述するための仕様で、YAMLやJSONでAPIを記述することができます。アプリケーションのドキュメントからAPIを定義したり、定義したAPIからコードを生成したり、反対に実装から、API定義を起こすこともできるそうです。今回はドキュメント（とはいっても自分でざっくり考えたもの）からAPI定義を記述するための Swagger Editor を使いました。 Swagger そのものは解説記事がたくさんあるので、そちらをご覧ください。これとか分かり易かったかな？
しかし、 AWS 特有の設定等は、標準の Swagger では記述できないため、このままではいちいち手作業で設定する必要が残ります。 そこで、API Gateway の Swagger 拡張を使って、AWS特有の設定も Swagger ファイルで定義してしまおう、という作業を行いました。
ということで、毎度の作業メモです。以下では、記述したい AWS の機能ごとにまとめてあります。
Cognito ユーザープールによるオーソライザーの設定方法
下記記事に Cognito ユーザープールによるオーソライザーを使う場合の Swagger 拡張の書き方がずばり載ってます。
REST API と Amazon Cognito ユーザープールを統合する - Amazon API Gateway
security definitions を定義して、各APIのメソッドの定義内の security で security definitions で定義した名前を参照すればOKです。 YAML だとこんな感じになります。
securityDefinitions: jm_test: type: apiKey name: Authorization in: header x-amazon-apigateway-authtype: cognito_user_pools x-amazon-apigateway-authorizer: providerARNs: - >- arn:aws:cognito-idp:ap-northeast-1:xxxxxxxxxxxx:userpool/ap-northeast-1_yyyyyyyyyyyyyyy type: cognito_user_pools
security: - jm_test: []
Lambda 関数
一番分かり易そうなのが、これかな。プロキシリソースを対象に、API Gateway で Lambdaプロキシ統合をする場合の Swagger 定義の例になります。
サンプルだけなら、これもいいかも。
必要なことは、 x-amazon-apigateway-integration を定義することになります。 uri に Lambda 関数のARNをベースにサンプルのように記述します。 この際、httpMethod は必ず POST にします（こちらのリファレンスのページの httpMethod に載ってますのでご確認ください）。
YAMLだとこんな感じになりました。
x-amazon-apigateway-integration: uri: >- arn:aws:apigateway:ap-northeast-1:lambda:path/2015-03-31/functions/（Lambda関数のARN）/invocations responses: default: statusCode: '200' passthroughBehavior: when_no_match httpMethod: POST contentHandling: CONVERT_TO_TEXT type: aws_proxy
なお、uri のフォーマットの説明はこれだ、というピンポイントのものがないのですが、
の２つのリファレンスの内容から、上記のような形式だと推測されます（pathの後ろのスラッシュ以降が Lambda 関数呼び出しAPIになってるようです）。 また、上記の例ではLambdaのバージョンは指定していないので、 Qualifier はつけていません。
CORS の設定
CORS も設定しておきましょう。こちらのサンプルがよくわかります。
API Gateway のインポート API を使用して、リソースで CORS を有効にする - Amazon API Gateway
まず、 CORS を有効としたいリソースに対して、 OPTIONS メソッドを定義します。 OPTIONS メソッドでは Mock 統合を指定します。 次に、 responses と x-amazon-apigateway-integration に 返すヘッダーの定義を追加します。サンプルの通りですね。
YAML だとこんな感じでした。
OPTIONS メソッドの定義
options: tags: - CORS summary: CORS support description: Enable CORS by returning correct headers consumes: - application/json produces: - application/json responses: '200': description: 200 response schema: $ref: '#/definitions/Empty' headers: Access-Control-Allow-Origin: type: string Access-Control-Allow-Methods: type: string Access-Control-Allow-Headers: type: string x-amazon-apigateway-integration: responses: default: statusCode: '200' responseParameters: method.response.header.Access-Control-Allow-Methods: '''GET,OPTIONS''' method.response.header.Access-Control-Allow-Headers: >- 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token' method.response.header.Access-Control-Allow-Origin: '''*''' passthroughBehavior: when_no_match requestTemplates: application/json: '{"statusCode": 200}' type: mock
x-amazon-apigateway-integration の method.response.header.Access-Control-Allow-Methods は対象とするメソッド名を記述していますが、 '*' でも問題ないかと思います。
APIのレスポンスにヘッダ宣言を含めます。
/api/sample/test: get: tags: - util summary: サンプル description: '' responses: '200': description: 成功時のレスポンス schema: $ref: '#/definitions/SuccessResponse' headers: Access-Control-Allow-Origin: type: string
x-amazon-apigateway-integration のレスポンスに Access-Control-Allow-Origin ヘッダに静的な値を設定します。
x-amazon-apigateway-integration: uri: >- arn:aws:apigateway:ap-northeast-1:lambda:path/2015-03-31/functions/（Lambda関数のARN）/invocations responses: default: statusCode: '200' responseParameters: method.response.header.Access-Control-Allow-Origin: '''*''' passthroughBehavior: when_no_match httpMethod: POST contentHandling: CONVERT_TO_TEXT type: aws_proxy
Lambda 関数を呼び出す権限の追加
以上を追加した Swagger ファイルを使って、API Gateway でインポートすると、無事に API が定義されます。一度 Swagger ファイルを作ってやれば何度でもインポートできるのでこれは便利ですね。
では、ということで、ステージにデプロイして、APIを呼び出すと、Lambda関数が呼び出せません。 なんでだろうか？と思い調べると、API Gateway に Lambda 関数を呼び出す権限が与えられていないから、ということでした。
いわれてみれば API Gateway のコンソールから Lambda 関数の呼び出しを設定する場合は、
のように、API Gateway に Lambda 関数を呼び出す権限を与えてもいいか？という確認画面がでて、これでOKを押すことで、Lambda関数を実行することができるとのことです（そんな画面あったなー、という感じですね）。
ということで、Lambda 関数の呼び出し権限を与える設定も行います。
今回は、Lambda 関数を呼び出す権限を持ったロールを定義し、これを Swagger で指定するという方法を取りたいと思います（ロールベースの権限設定）。
なお、API Gateway に必要な権限については、下記に詳しいと思います。
IAM アクセス許可により API へのアクセスを制御する - Amazon API Gateway
ロールの作成
API Gateway が Lambda 関数を呼び出す権限を持ったロールを作成したいと思います（実際の権限は下記チュートリアルに詳しいです）。
チュートリアル: 2 つの AWS のサービス統合と 1 つの Lambda 非プロキシ統合を使用して Calc REST API を作成する - Amazon API Gateway
今回は、AWSのコンソールを使って作成したいと思います。
コンソールから、IAMを選択し、『ロールの作成』を選択します。
次に表示された画面で、『AWSサービス』を選択し
下のサービス一覧のリストから『API Gateway』を選択します。
このとき、画面下部の『ユースケースの選択』が選ばれた状態になっています。 『次のステップ』ボタンを押して、次の場面に進むと、ポリシーを設定できる画面になります。
が、ここでは、先ほどの『ユースケース』に対応するものしか選べないようで自由に選択することができませんでした。 なので、一旦このまま先に進みます。
適当なロール名を入力して、『ロールの作成』ボタンを押せば、ロールが作成されます。
次に作成されたロールを選択すると概要が表示されます。
この画面で『ポリシーをアタッチします』を選び、Lambda関数呼び出し権限を追加します。 フィルタを使って、Lambda関数呼び出しの権限『AWSLambdaRole』を探して、チェックをつけます。
『ポリシーのアタッチ』ボタンを押せば、ロールにLambda関数呼び出し権限が追加されます。
ロールの指定
ロールの指定方法は、
x-amazon-apigateway-integration オブジェクト - Amazon API Gateway
に記載されているように credential にロールのARNを指定すればよいようです。
YAML だとこんな感じになりました。
x-amazon-apigateway-integration: credentials: 'arn:aws:iam::xxxxxxxxxxxx:role/yyyyyyyyyyyyyyyyyyyy' uri: >-
x-amazon-apigateway-integration に対して追記するので、Lambda 関数を呼び出す全てのAPIに対して設定が必要になります。
この設定を追加後、再度 Swagger ファイルをインポートして、作成した API にアクセスすると問題なく Lambda 関数が呼べました。
（参考）別の権限追加方法
リファレンスを調べてみると API Gateway からLambda 関数の呼び出しは、Lambda 側に設定を持たせることもできるようです（リソースベースの権限設定）。
AWS Lambda アクセス許可 - AWS Lambda
こちらの方法のほうが、どのAWSサービスから Lambda 関数が呼ばれているかを把握できるので便利だ、というようなことが書いてありました。
今回はこちらの方法はとらなかったので、機会があれば試してみたいと思います。
たねあかし
Swagger 拡張による記述は大変便利ですが、上記の記述方法を調べていくのって大変ですよね？ 実は、上記に述べた Swagger 拡張は一からすべて調べて書いたのではなく、一旦手作業で API Gateway を設定後、ステージの『エクスポート』にある『Swagger + API Gateway 拡張でエクスポート』を実行し、作成されたファイル（Swagger拡張を含むAPI定義）を元に必要な記述を調べていきました。
こうすれば、設定したい機能に必要な Swagger 拡張のキーワード等が分かるので、そこから詳しく調べていくことができます。
ここまで設定ができると API の追加・変更があった場合も API Gateway 側で手作業で設定することが（現時点では）ほぼなくなるので非常に簡単になりました。 Swagger 拡張、なかなか使えますね。
