Amazon API Gateway Swagger ImporterでAPIを一発で定義する

2015.07.22

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

ども、大瀧です。
Amazon API Gateway、皆さん触ってますか?APIサーバーに関する様々な機能があって便利ですが、Management ConsoleでのAPI定義や設定が煩わしいと感じる方もいると思います。そこで今回は、Amazon API Gateway Swagger Importerを利用してAPI定義を一括でやってみたいと思います。

セットアップ

  • 動作確認環境
    • OS : Mac OS X Yosemite
    • AWS CLI : 1.7.39

Mavenを利用するために、HomebrewでJavaと一緒にインストールしておきます。

$ brew install Caskroom/cask/java
$ brew install maven

続いて、GitHubリポジトリをCloneし、README.mdに従いMavenを実行します。

$ git clone https://github.com/awslabs/aws-apigateway-swagger-importer.git
$ cd aws-apigateway-swagger-importer/
$ mvn assembly:assembly
  : 
$ ./aws-api-import.sh
Usage: aws-api-import [options] Path to API definition file to import
  Options:
    --create, -c
       Create a new API
       Default: false
    --deploy, -d
       Stage used to deploy the API
        --help

       Default: false
    --test, -t
       Delete the API after import (create only)
       Default: false
    --update, -u
       API ID to import swagger into an existing API
$

これでセットアップ完了です。

動作確認

リポジトリ内にテスト用のSwagger Specファイルがいくつかあるので、適当なものからAPI GatewayのAPIを生成してみます。AWSのアクセスキーなどは、AWS CLIなどと同様、~/.aws/credentialファイルのdefaultプロファイルから引用されるようです。

tst/resources/petstore-simple.json

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Swagger Petstore",
    "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification",
    "termsOfService": "http://swagger.io/terms/",
    "contact": {
      "name": "Swagger API Team"
    },
    "license": {
      "name": "MIT"
    }
  },
  "host": "petstore.swagger.io",
  "basePath": "/api",
  "schemes": [
    "http"
  ],
  :

API作成は--create <Swagger Specファイル名>です。

$ ./aws-api-import.sh --create tst/resources/petstore-simple.json
2015-07-22 17:11:01,014 INFO - Attempting to create API from Swagger definition. Swagger file: tst/resources/petstore-simple.json
reading from tst/resources/petstore-simple.json
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
2015-07-22 17:11:01,142 INFO - Parsed Swagger with 2 paths
2015-07-22 17:11:01,146 INFO - Creating API with name Swagger Petstore
2015-07-22 17:11:02,506 INFO - Removing default model Empty
2015-07-22 17:11:02,850 INFO - Removing default model Error
2015-07-22 17:11:03,161 INFO - Creating model for api id fe0b503ua6 with name Pet
2015-07-22 17:11:03,380 INFO - Generated json-schema for model Pet: {"required":["id","name"],"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"tag":{"type":"string"}},"type":"object","definitions":{}}
2015-07-22 17:11:03,669 INFO - Creating model for api id fe0b503ua6 with name PetInput
2015-07-22 17:11:03,681 INFO - Generated json-schema for model PetInput: {"allOf":[{"$ref":"#/definitions/Pet"},{"properties":{"id":{"type":"integer","format":"int64"}}}],"definitions":{"Pet":{"required":["id","name"],"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"tag":{"type":"string"}},"type":"object"}}}
2015-07-22 17:11:03,977 INFO - Creating model for api id fe0b503ua6 with name ErrorModel
2015-07-22 17:11:03,986 INFO - Generated json-schema for model ErrorModel: {"required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}},"type":"object","definitions":{}}
2015-07-22 17:11:04,592 INFO - Creating resource 'api' with parent 'null'
2015-07-22 17:11:05,896 INFO - Creating resource 'pets' with parent 'api'
2015-07-22 17:11:06,951 INFO - Found input model reference PetInput
2015-07-22 17:11:07,561 INFO - Creating method response for api fe0b503ua6 and method POST and status 200
2015-07-22 17:11:07,816 INFO - Found reference to existing model Pet
2015-07-22 17:11:08,382 WARN - Default response not supported, skipping
2015-07-22 17:11:08,383 INFO - Creating method for api id fe0b503ua6 and resource id 08gvh1 with method post
2015-07-22 17:11:09,414 INFO - Creating method response for api fe0b503ua6 and method GET and status 200
2015-07-22 17:11:09,678 INFO - Creating new model referenced from response: petresponse
2015-07-22 17:11:09,679 INFO - Creating model for api id fe0b503ua6 with name petresponse
2015-07-22 17:11:09,689 INFO - Generated json-schema for model petresponse: {"type":"array","items":{"$ref":"#/definitions/Pet"},"definitions":{"Pet":{"required":["id","name"],"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"tag":{"type":"string"}},"type":"object"}}}
2015-07-22 17:11:10,633 WARN - Default response not supported, skipping
2015-07-22 17:11:10,633 INFO - Creating method parameter for api fe0b503ua6 and method GET with name method.request.querystring.tags
2015-07-22 17:11:10,896 INFO - Creating method parameter for api fe0b503ua6 and method GET with name method.request.querystring.limit
2015-07-22 17:11:11,176 INFO - Creating method for api id fe0b503ua6 and resource id 08gvh1 with method get
2015-07-22 17:11:12,487 INFO - Creating resource '{id}' with parent 'pets'
2015-07-22 17:11:14,166 INFO - Creating method response for api fe0b503ua6 and method GET and status 200
2015-07-22 17:11:14,421 INFO - Found reference to existing model Pet
2015-07-22 17:11:15,035 WARN - Default response not supported, skipping
2015-07-22 17:11:15,036 INFO - Creating method parameter for api fe0b503ua6 and method GET with name method.request.path.id
2015-07-22 17:11:15,338 INFO - Creating method for api id fe0b503ua6 and resource id 9qgv9w with method get
2015-07-22 17:11:16,572 INFO - Creating method response for api fe0b503ua6 and method DELETE and status 204
2015-07-22 17:11:17,334 WARN - Default response not supported, skipping
2015-07-22 17:11:17,335 INFO - Creating method parameter for api fe0b503ua6 and method DELETE with name method.request.path.id
2015-07-22 17:11:17,619 INFO - Creating method for api id fe0b503ua6 and resource id 9qgv9w with method delete
$

できました!Management Consoleを見てみると。。。

apigateway-swagger

ResourceとMethodが定義されていますね!

まとめ

API Gateway Swagger ImporterでAPI定義を一括実行する様子をご紹介しました。 ただ、API Gatewayに合わせたSpecが書かれていないと、設定が抜けたりするようです。今回はIntegration設定がMethodに入っていないため、空のMethod定義になっていました。

また、API作成以外にアップデートなどもできるようなので、CloudFormationのような運用もできるかもしれません。