ども、 @kimihomです。
前回は、Grape on Rails での開発初めまでを紹介した。 API のお話もこれで最後。Grape Swagger で作った Swagger ドキュメントを Amazon API Gateway 上で動くように動作させる。
swagger.json の取得
まず、今回は作成した Swagger 形式のドキュメントを、 JSON 形式で出力する必要がある。その出力した JSON ファイルを、aws-apigateway-importer を用いて Amazon API Gateway に取り込むようにするのである。
てことで調べてみると、 grape-swagger は 現状では Swagger 1.2 のみの対応で、Swagger 2.0 対応の予定は当分なさそうな雰囲気だった。そのため、Swagger 2.0 形式で出力してくれる、Ruby Swaggerを利用しよう。
bundle exec rake swagger:grape:generate_doc\[API::Root\] bundle exec rake swagger:compile_doc
この2つを実行すると、doc/swagger.json ファイルを出力してくれる。
swagger.json の修正
このまま API Gateway Importer を使っても、うまく動かない。以下のことをする必要がある。
- V1:: などのネームスペースで区切った
::は使えないので削除する - 配列を返すSuccessful~ の項目をそれぞれユニークな名前にセット ~ArrayEntity。こうしないとAPI Gateway 側で任意の名前になってしまう。
- swagger.json内にあるcontent ~ の項目をそれぞれユニークな名前にセット ~Param。同様に名前付けしないとAPI Gateway 側で変な名前がついてしまう
aws-apigateway-importer の利用
これでいよいよ API Gateway に swagger ファイルをインポートさせることができるようになる。
セットアップ $ brew install Caskroom/cask/java $ brew install maven $ git clone https://github.com/awslabs/aws-apigateway-swagger-importer.git $ cd aws-apigateway-swagger-importer/ $ mvn assembly:assembly $ ./aws-api-import.sh --create /path/to/swagger.json
こうすると、見事 API Gateway 側で定義された メソッド一覧とモデル一覧が生成される。
API Gateway 側での設定
ここからは一個ずつ面倒な設定。。 ここら辺、 aws-apigateway-swagger-importer にもやり方はあるようなんだけどあまりにもドキュメントが少ないのでそれに手間暇かけるよりかは一個一個設定した方がいいと判断。
API Gateway のそれぞれのメソッドにアクセスすると、まずはendpoint url を設定するように言われる。全て入力していこう。
そうすると、 API Gateway のいつもの画面 "Method Request", "Integration Request", "Integration Response", "Method Response" の設定が始まる。この4つ最初はなんで"Method Request", "Integration Request みたいに分かれているのだろう？と疑問に思ったので、まず自分なりの解釈を説明する。
"意味不明なパラメータや REST じゃない、酷いAPIを自社サービスで持っている"ということを前提として考えていただきたい。この場合、まずAPI Gateway 側でセットした ちゃんとした受け取りパラメータの入り口 を用意する必要がある。これが"Method Request" である。そしてそこで受け取った綺麗なパラメータを酷いAPI 側で認識できるように変換してあげる必要がある。これが "Integration Request" である。 Response もそれと同様で、変換作業と綺麗なレスポンスを分けるために2つがある。
そんで、aws-apigateway-swagger-importer 側でやってくれるのは、"Method Request"と"Method Response"の2つのみ。あとは仕方ないので一個一個設定してあげる。特にURLやPATHパラメータ、Headerトークンを "Integration Request" の方にも設定してあげなければならない。そうしないとendpoint url にパラメータが飛んでこない。
諸々設定が完了したらとは Deploy API で公開しよう。見事 API の完成だ。それができれば、 API Gateway でできる他のことも見てみたりすると、Amazon API Gateway の便利さを知ることになるだろう。
