Full sample code for this article is available on Github.

Aamazon’s API Gateway supports the direct importing of Swagger specification files using CloudFormation rules. To do this, you have two choices. Injecting the swagger.json or swagger.yaml file directly into the Body field of the CloudFormation template, or uploading the swagger.json or swagger.yaml file to an S3 location and setting that location as the BodyS3Location field of the CloudFormation template.

A minimal YAML template is listed below:

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  PlayersAPI:
    Type: AWS::ApiGateway::RestApi
    Properties:
      Name: Player API
      Description: A demo API for Player management
      Body: # Swagger Specification body goes here

We can re-use the Player API Swagger specification from a previous article as the Body of the CloudFormation template.

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  PlayersAPI:
    Type: AWS::ApiGateway::RestApi
    Properties:
      Name: Player API
      Description: A demo API for Player management
      Body:
        swagger: '2.0'
        info:
          title: Player API
          description: A simple API for Player resources
          version: 1.0.1
          contact:
            name: Kevin Sookocheff
            url: https://sookocheff.com
            email: kevin@sookocheff.com
          license:
            name: Apache 2.0
            url: http://www.apache.org/licenses/LICENSE-2.0.html
          termsOfService: http://sookocheff.com/terms
        paths:
          "/player/{id}":
            get:
              description: Returns a Player resource
              produces:
              - application/json
              responses:
                '200':
                  description: A player resource.
                  schema:
                    "$ref": "#/definitions/Player"
            parameters:
            - name: id
              in: path
              description: Identifier of player to retreive
              required: true
              type: string
        definitions:
          Player:
            type: object
            properties:
              playerId:
                type: string
              alias:
                type: string
              displayName:
                type: string
              profilePhotoUrl:
                type: string
            required:
            - playerId
            - alias

With this template in hand, we can use CloudFormation to deploy a working Swagger API.

$ aws cloudformation create-stack --stack-name playerapi --template-body file:///Users/kevinsookocheff/Projects/swagger-demo/cloudformation.yaml --region us-west-2
{
    "StackId": "arn:aws:cloudformation:us-west-2:****:stack/playerapi/****"
}

You can view the deploy in progress and the finished result using the AWS Management Console.

Deploy In Progress

API Gateway Extensions to Swagger

The API Gateway also defines AWS specific extensions to the Swagger specification that allow you to fully describe an API Gateway definition in your Swagger file.

For example, the API Gateway extensions allow you to configure your endpoint as a Proxy to a particular HTTP endpoint directly in your Swagger definition. In our case, we can forward any requests to received by API Gateway to a backend service that implements the Player API by using the x-amazon-apigateway-integration property.

x-amazon-apigateway-integration:
  type: http
  responses:
    default:
      statusCode: '200'
  httpMethod: GET
  uri: http://api.example.com

The API Gateway extensions are enabled on a per endpoint basis, so place the integration field in the full YAML file as part of the GET endpoint definition.

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  PlayersAPI:
    Type: AWS::ApiGateway::RestApi
    Properties:
      Name: Player API
      Description: A demo API for Player management
      Body:
        swagger: '2.0'
        info:
          title: Player API
          description: A simple API for Player resources
          version: 1.0.1
          contact:
            name: Kevin Sookocheff
            url: https://sookocheff.com
            email: kevin@sookocheff.com
          license:
            name: Apache 2.0
            url: http://www.apache.org/licenses/LICENSE-2.0.html
          termsOfService: http://sookocheff.com/terms
        paths:
          "/player/{id}":
            get:
              description: Returns a Player resource
              produces:
              - application/json
              responses:
                '200':
                  description: A player resource.
                  schema:
                    "$ref": "#/definitions/Player"
              x-amazon-apigateway-integration:
                type: http
                responses:
                  default:
                    statusCode: '200'
                httpMethod: GET
                uri: http://api.example.com
            parameters:
            - name: id
              in: path
              description: Identifier of player to retreive
              required: true
              type: string
        definitions:
          Player:
            type: object
            properties:
              playerId:
                type: string
              alias:
                type: string
              displayName:
                type: string
              profilePhotoUrl:
                type: string
            required:
            - playerId
            - alias

Deploying this API will show the full integration with API Gateway.

Deployed API