プログラマーのメモ書き

伊勢在住のプログラマーが気になることを気ままにメモったブログです

Swagger による API Gateway の定義

API Gateway を使う際、だんだんAPIの数が増えてくる(リソース・メソッドが増えてくる)と、コンソールで定義するのが大変になってきます。 特に、APIのリネームなんてことが起こったら、嫌になってきます。

なので、それを避けるために、API定義を Swagger で記述して、それを API Gateway にインポートさせて API 定義を簡単に行えるようにしています。

※ Swagger とは、APIを記述するための仕様で、YAMLやJSONでAPIを記述することができます。アプリケーションのドキュメントからAPIを定義したり、定義したAPIからコードを生成したり、反対に実装から、API定義を起こすこともできるそうです。今回はドキュメント(とはいっても自分でざっくり考えたもの)からAPI定義を記述するための Swagger Editor を使いました。 Swagger そのものは解説記事がたくさんあるので、そちらをご覧ください。これとか分かり易かったかな?

qiita.com

しかし、 AWS 特有の設定等は、標準の Swagger では記述できないため、このままではいちいち手作業で設定する必要が残ります。 そこで、API Gateway の Swagger 拡張を使って、AWS特有の設定も Swagger ファイルで定義してしまおう、という作業を行いました。

ということで、毎度の作業メモです。以下では、記述したい AWS の機能ごとにまとめてあります。

Cognito ユーザープールによるオーソライザーの設定方法

下記記事に Cognito ユーザープールによるオーソライザーを使う場合の Swagger 拡張の書き方がずばり載ってます。

API をユーザープールと統合 - 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 のフォーマットの説明はこれだ、というピンポイントのものがないのですが、

の2つのリファレンスの内容から、上記のような形式だと推測されます(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 関数の呼び出しを設定する場合は、

f:id:junichim:20180824124228p:plain

のように、API Gateway に Lambda 関数を呼び出す権限を与えてもいいか?という確認画面がでて、これでOKを押すことで、Lambda関数を実行することができるとのことです(そんな画面あったなー、という感じですね)。

ということで、Lambda 関数の呼び出し権限を与える設定も行います。

今回は、Lambda 関数を呼び出す権限を持ったロールを定義し、これを Swagger で指定するという方法を取りたいと思います(ロールベースの権限設定)。

なお、API Gateway に必要な権限については、下記に詳しいと思います。

IAM アクセス権限により API へのアクセスを制御する - Amazon API Gateway

ロールの作成

API Gateway が Lambda 関数を呼び出す権限を持ったロールを作成したいと思います(実際の権限は下記チュートリアルに詳しいです)。

AWS Lambda 関数の API GatewayAPI を作成する - Amazon API Gateway

今回は、AWSのコンソールを使って作成したいと思います。

コンソールから、IAMを選択し、『ロールの作成』を選択します。

f:id:junichim:20180824124924p:plain

次に表示された画面で、『AWSサービス』を選択し

f:id:junichim:20180824125100p:plain

下のサービス一覧のリストから『API Gateway』を選択します。

f:id:junichim:20180824125221p:plain

このとき、画面下部の『ユースケースの選択』が選ばれた状態になっています。 『次のステップ』ボタンを押して、次の場面に進むと、ポリシーを設定できる画面になります。

f:id:junichim:20180824125401p:plain

が、ここでは、先ほどの『ユースケース』に対応するものしか選べないようで自由に選択することができませんでした。 なので、一旦このまま先に進みます。

f:id:junichim:20180824125631p:plain

適当なロール名を入力して、『ロールの作成』ボタンを押せば、ロールが作成されます。

次に作成されたロールを選択すると概要が表示されます。

f:id:junichim:20180824125847p:plain

この画面で『ポリシーをアタッチします』を選び、Lambda関数呼び出し権限を追加します。 フィルタを使って、Lambda関数呼び出しの権限『AWSLambdaRole』を探して、チェックをつけます。

f:id:junichim:20180824130047p:plain

『ポリシーのアタッチ』ボタンを押せば、ロールに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定義)を元に必要な記述を調べていきました。

f:id:junichim:20180824132738p:plain

こうすれば、設定したい機能に必要な Swagger 拡張のキーワード等が分かるので、そこから詳しく調べていくことができます。

ここまで設定ができると API の追加・変更があった場合も API Gateway 側で手作業で設定することが(現時点では)ほぼなくなるので非常に簡単になりました。 Swagger 拡張、なかなか使えますね。