読者です 読者をやめる 読者になる 読者になる

ボクココ

サービス開発を成功させるまでの歩み

API Gateway 用の Swagger JSON を生成する方法

ども、@kimihom です。

久々の AWS ネタは Amazon API Gateway のお話。

f:id:cevid_cpp:20170327191713p:plain

Amazon API Gateway を使えば、 Swagger 形式のドキュメントをアップロードするだけで、APIの “側” を作ってくれる。この “側” を API Gateway で作っておけば、キャッシュを有効化できたり、大量APIリクエスト防止のスロットリング(リクエスト数の制限)ができたり、外部呼び出し用の iOS/Android/JavaScript SDK を生成できたり、CloudWatch にログを吐き出したりすることができる。

今回は、Swagger の話は細かくは書かない。興味があれば以前の記事を参照していただきたい。

さて、上記の記事は1年前なのでちょっと古かったりするため、今回はより完璧に “API Gateway 用の Swagger JSON を生成する方法” をご紹介しよう。

swagger.json の生成

まず swagger.json を書き出す。より詳細のコマンドは以下の Github を参照していただきたい。

GitHub - Gild/ruby-swagger: A super-duper-simple library to read or create Swagger API documents.

# Generate a swagger 2.0-compatible documentation from the metadata stored into doc/swagger
bundle exec rake swagger:grape:generate_doc\[API::Root\]
# Build all the API clients
bundle exec rake swagger:compile_doc

これで書き出された swagger.json を Amazon API Gateway でインポートすれば、確かに API の定義がされた状態まで形作ってくれる。

f:id:cevid_cpp:20170327190645p:plain

しかし、この状態のままでは、統合リクエストや統合レスポンスの定義がされていないままアップロードされるため、結局一個ずつ定義していかなければならないという痛すぎる問題が起きる。せっかくなら swagger.json をアップロードしただけで、スパッとデプロイできるようにしたいよね!?

てことで今回はその方法をご紹介。

まずは面倒でも手動でセットせよ!

例えば CORS を有効にしたいといった場合、swagger 形式で上げた後に先ほどのメニューより CORS の有効化を押せば勝手に設定を変えてくれる。これはこれで手軽で便利である。その他諸々 統合リクエスト/統合レスポンスの設定をまずは完璧にセットしてデプロイし、動作を確認しよう。

んでここがキモなんだけど、これでOK!となったら、[ステージ] -> [エクスポート] -> [Swagger + API Gateway 拡張でエクスポート] を選択しよう。ここでエクスポートした json が、あなたにとって理想の JSON 形式のファイルとなる。

そこには、例えば x-amazon-apigateway-integration といったキーの JSON が追加で埋め込まれている!

つまり、書き出した swagger.json を、x-amazon-apigateway-integration などが入った JSON に再度 データを突っ込めば、API Gateway でインポートした時に全部が定義された完璧な状態を一発でアップロードできるようになるのである!

てことでここは単純な Ruby プログラムの時間である。 Rake タスクとして定義しておくのが良いだろう。

desc 'Swagger ドキュメントに AWS 関連情報を付加'
namespace :swagger do
  task :compile_aws_doc do |task, args|

    json_data = open(json_file_path) do |io|
      JSON.load(io)
    end

    json_data['paths'].each do |path, methods|
      methods.each do |method, content|
        # API Gateway settings
        content['x-amazon-apigateway-integration'] = {}
        #....
     end
  end
end

これがうまくできれば、ポチッと rake タスクを実行すれば良いことになる。

rake swagger:compile_aws_doc

一発で完璧な API を生成できた時の気持ち良さはたまらんね。

終わりに

API Gateway のメリットを知った上で、サクッとSwagger 定義に則った API Gateway の API を作ってみてはいかがだろうか。

Swagger 形式にまで出力できれば、 API Gateway に載せることはそこまで難しくはない。ぜひ挑戦してみよう。