Setting up SwaggerUI in AWS with S3/API Gateway/GitHub Actions

This simply defines consistent, constant, data across our module.

locals {
  service_name = "monsternames"
  static_bucket_name = lower("${var.account}-${var.environment}-${local.service_name}-static-content")
  default_tags = {
    account: var.account,
    environment: var.environment,
    source: var.source_repository,
    service: local.service_name
  }
  base_path = lower("/${var.environment}/${local.service_name}/")
}

This defines the inputs that our module can have. As always, it’s good practice to:

• Explicitly define inputs

• Explicitly define types

• Explicitly define permissible values

variable "environment" {
  description = "The environment within which we're instantiating this module."
  type        = string
  validation {
    condition = anytrue([
      var.environment == "Prod",
      var.environment == "Stage",
      var.environment == "Dev"
    ])
    error_message = "Only the following environments are supported: Prod/Stage/Dev"
  }
}
variable "account" {
  description = "The AWS account within which we're instantiating this module."
  type = string
}
variable "static_content_versioning" {
  description = "Whether to enable versioning on the static content S3 bucket."
  type = string
  default = "Enabled"
  validation {
    condition = anytrue([
      var.static_content_versioning == "Enabled",
      var.static_content_versioning == "Suspended",
      var.static_content_versioning == "Disabled"
    ])
    error_message = "Only the following environments are supported: Enabled/Suspended/Disabled"
  }
}
variable "source_repository" {
  description = "Terraform repository managing this module, used for tagging purposes."
  type = string
  default = "terraform.aws"
}
variable "static_content_upload_users" {
  description = "IAM users whom should be allowed to assume static content upload role"
  type = list(string)
  default = []
}

This file actually creates our s3 bucket, with appropriate versioning and tagging for cost tracking:

resource "aws_s3_bucket" "static_content" {
  bucket = local.static_bucket_name
  tags = local.default_tags
}
resource aws_s3_bucket_versioning "static_content_versioning" {
  depends_on = [aws_s3_bucket.static_content]
  bucket = aws_s3_bucket.static_content.id
  versioning_configuration {
    status = var.static_content_versioning
  }
}
resource "aws_s3_bucket_ownership_controls" "static_content_ownership" {
  bucket = aws_s3_bucket.static_content.id
  rule {
    object_ownership = "BucketOwnerPreferred"
  }
}
resource "aws_s3_bucket_acl" "static_content_acl" {
  depends_on = [aws_s3_bucket_ownership_controls.static_content_ownership]
  bucket = aws_s3_bucket.static_content.id
  acl    = "private"
}

data "aws_iam_policy_document" "upload" {
  statement {
    sid = "1"
    effect = "Allow"
    actions = [
      "s3:ListBucket"
    ]
    resources = [
      "arn:aws:s3:::${aws_s3_bucket.static_content.id}"
    ]
  }
  statement {
    sid = "2"
    effect = "Allow"
    actions = [
      "s3:Put*",
      "s3:Get*",
      "s3:DeleteObject"
    ]
    resources = [
      "arn:aws:s3:::${aws_s3_bucket.static_content.id}/*"
    ]
  }
}
resource "aws_iam_policy" "upload" {
  name        = "${local.static_bucket_name}-upload-policy"
  path        = "${local.base_path}iam/"
  description = "Policy which allows upload access to ${local.static_bucket_name} - managed by Terraform"
  policy = data.aws_iam_policy_document.upload.json
}

Here we setup a new IAM group - which will have the previous policy attached - in order to manage user upload access to the bucket.

resource "aws_iam_group" "static_content_upload" {
  name        = "${local.static_bucket_name}-static-content-upload-group"
  path        = "${local.base_path}iam/"
}
resource "aws_iam_group_membership" "static_content_upload" {
  group = aws_iam_group.static_content_upload.id
  name  = "${aws_iam_group.static_content_upload.name}-membership"
  users = var.static_content_upload_users
}
resource "aws_iam_group_policy_attachment" "attachments" {
  group = aws_iam_group.static_content_upload.id
  policy_arn = aws_iam_policy.upload.arn
}

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create
<= read (data resources)
Terraform will perform the following actions:
  # module.monsternames.data.aws_iam_policy_document.upload will be read during apply
  # (config refers to values not yet known)
<= data "aws_iam_policy_document" "upload" {
      + id   = (known after apply)
      + json = (known after apply)
      + statement {
          + actions   = [
              + "s3:ListBucket",
            ]
          + effect    = "Allow"
          + resources = [
              + (known after apply),
            ]
          + sid       = "1"
        }
      + statement {
          + actions   = [
              + "s3:DeleteObject",
              + "s3:Get*",
              + "s3:Put*",
            ]
          + effect    = "Allow"
          + resources = [
              + (known after apply),
            ]
          + sid       = "2"
        }
    }
  # module.monsternames.aws_iam_group.static_content_upload will be created
  + resource "aws_iam_group" "static_content_upload" {
      + arn       = (known after apply)
      + id        = (known after apply)
      + name      = "sudoblark-prod-monsternames-static-content-static-content-upload-group"
      + path      = "/prod/monsternames/iam/"
      + unique_id = (known after apply)
    }
  # module.monsternames.aws_iam_group_membership.static_content_upload will be created
  + resource "aws_iam_group_membership" "static_content_upload" {
      + group = (known after apply)
      + id    = (known after apply)
      + name  = "sudoblark-prod-monsternames-static-content-static-content-upload-group-membership"
      + users = [
          + "github_actions",
        ]
    }
  # module.monsternames.aws_iam_group_policy_attachment.attachments will be created
  + resource "aws_iam_group_policy_attachment" "attachments" {
      + group      = (known after apply)
      + id         = (known after apply)
      + policy_arn = (known after apply)
    }
  # module.monsternames.aws_iam_policy.upload will be created
  + resource "aws_iam_policy" "upload" {
      + arn         = (known after apply)
      + description = "Policy which allows upload access to sudoblark-prod-monsternames-static-content - managed by Terraform"
      + id          = (known after apply)
      + name        = "sudoblark-prod-monsternames-static-content-upload-policy"
      + path        = "/prod/monsternames/iam/"
      + policy      = (known after apply)
      + policy_id   = (known after apply)
      + tags_all    = (known after apply)
    }
  # module.monsternames.aws_s3_bucket.static_content will be created
  + resource "aws_s3_bucket" "static_content" {
      + acceleration_status         = (known after apply)
      + acl                         = "private"
      + arn                         = (known after apply)
      + bucket                      = "sudoblark-prod-monsternames-static-content"
      + bucket_domain_name          = (known after apply)
      + bucket_regional_domain_name = (known after apply)
      + force_destroy               = false
      + hosted_zone_id              = (known after apply)
      + id                          = (known after apply)
      + object_lock_enabled         = (known after apply)
      + region                      = (known after apply)
      + request_payer               = (known after apply)
      + tags                        = {
          + "account"     = "sudoblark"
          + "environment" = "Prod"
          + "service"     = "monsternames"
          + "source"      = "github.com/sudoblark/terraform.aws"
        }
      + tags_all                    = {
          + "account"     = "sudoblark"
          + "environment" = "Prod"
          + "service"     = "monsternames"
          + "source"      = "github.com/sudoblark/terraform.aws"
        }
      + website_domain              = (known after apply)
      + website_endpoint            = (known after apply)
      + object_lock_configuration {
          + object_lock_enabled = (known after apply)
          + rule {
              + default_retention {
                  + days  = (known after apply)
                  + mode  = (known after apply)
                  + years = (known after apply)
                }
            }
        }
      + server_side_encryption_configuration {
          + rule {
              + bucket_key_enabled = (known after apply)
              + apply_server_side_encryption_by_default {
                  + kms_master_key_id = (known after apply)
                  + sse_algorithm     = (known after apply)
                }
            }
        }
      + versioning {
          + enabled    = (known after apply)
          + mfa_delete = (known after apply)
        }
    }
  # module.monsternames.aws_s3_bucket_acl.static_content_acl will be created
  + resource "aws_s3_bucket_acl" "static_content_acl" {
      + acl    = "private"
      + bucket = (known after apply)
      + id     = (known after apply)
      + access_control_policy {
          + grant {
              + permission = (known after apply)
              + grantee {
                  + display_name  = (known after apply)
                  + email_address = (known after apply)
                  + id            = (known after apply)
                  + type          = (known after apply)
                  + uri           = (known after apply)
                }
            }
          + owner {
              + display_name = (known after apply)
              + id           = (known after apply)
            }
        }
    }
  # module.monsternames.aws_s3_bucket_ownership_controls.static_content_ownership will be created
  + resource "aws_s3_bucket_ownership_controls" "static_content_ownership" {
      + bucket = (known after apply)
      + id     = (known after apply)
      + rule {
          + object_ownership = "BucketOwnerPreferred"
        }
    }
  # module.monsternames.aws_s3_bucket_versioning.static_content_versioning will be created
  + resource "aws_s3_bucket_versioning" "static_content_versioning" {
      + bucket = (known after apply)
      + id     = (known after apply)
      + versioning_configuration {
          + mfa_delete = (known after apply)
          + status     = "Enabled"
        }
    }
Plan: 8 to add, 0 to change, 0 to destroy.

# Copyright (c) 2023, Sudoblark Ltd
#
# All rights reserved.
#
# This source code is licensed under the BSD 3 clause license found in the
# LICENSE file in the root directory of this source tree.
openapi: 3.0.1
info:
  title: Monsternames - OpenAPI 3.0
  description: |-
    This is a relatively simple RESTAPI, based on the OpenAPI 3.0 specification, which generates pseudo-random names for
    common fantasy monsters.
  license:
    name: BSD 3 clause
    url: https://github.com/sudoblark/monsternames.open-api/blob/main/LICENSE.txt
  version: 1.0.11
externalDocs:
  description: Source API definition
  url: https://github.com/sudoblark/monsternames.open-api/
servers:
  - url: https://monsternames-api.com/api/v1.0
tags:
  - name: goatmen
    description: Names themed on cute fluffy animals
  - name: goblin
    description: Names themed on washed out wrestlers/average blokes
  - name: ogre
    description: Names themed on cavemen like speech
  - name: orc
    description: Names themed on {noun} + {silly moniker}
  - name: skeleton
    description: Names themed on 18th Century British Gentlemen
  - name: troll
    description: Names themed on a Scandinavian twist
paths:
  /goatmen:
    post:
      summary: Add pseudo-random name options
      security:
        - ApiKeyAuth: [ApiKeyAuth]
      tags:
        - goatmen
      requestBody:
        description: Add first name
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FirstNameModel"
            examples:
              first_name:
                $ref: "#/components/examples/FirstName"
      responses:
        "200":
          $ref: "#/components/responses/200PostFirstName"
        "400":
          $ref: "#/components/responses/400PostInvalidBody"
        "409":
          $ref: "#/components/responses/409PostAlreadyExists"
    get:
      summary: Retrieve a pseudo-random name
      tags:
        - goatmen
      responses:
        "200":
          $ref: "#/components/responses/200GetFirstName"
  /goblin:
    post:
      summary: Add pseudo-random name options
      security:
        - ApiKeyAuth: [ApiKeyAuth]
      tags:
        - goblin
      requestBody:
        description: Add first and/or last name
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - $ref: "#/components/schemas/FirstNameModel"
                - $ref: "#/components/schemas/LastNameModel"
                - $ref: "#/components/schemas/FirstAndLastNameModel"
            examples:
              first_name:
                $ref: "#/components/examples/FirstName"
              last_name:
                $ref: "#/components/examples/LastName"
              first_and_last_name:
                $ref: "#/components/examples/FirstAndLastName"
      responses:
        "200":
          $ref: "#/components/responses/200PostFirstAndLastName"
        "400":
          $ref: "#/components/responses/400PostInvalidBody"
        "409":
          $ref: "#/components/responses/409PostAlreadyExists"
    get:
      summary: Retrieve a pseudo-random name
      tags:
        - goblin
      responses:
        "200":
          $ref: "#/components/responses/200GetFirstAndLastName"
  /ogre:
    post:
      summary: Add pseudo-random name options
      security:
        - ApiKeyAuth: [ApiKeyAuth]
      tags:
        - ogre
      requestBody:
        description: Add first name
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FirstNameModel"
            examples:
              first_name:
                $ref: "#/components/examples/FirstName"
      responses:
        "200":
          $ref: "#/components/responses/200PostFirstName"
        "400":
          $ref: "#/components/responses/400PostInvalidBody"
        "409":
          $ref: "#/components/responses/409PostAlreadyExists"
    get:
      summary: Retrieve a pseudo-random name
      tags:
        - ogre
      responses:
        "200":
          $ref: "#/components/responses/200GetFirstName"
  /orc:
    post:
      summary: Add pseudo-random name options
      security:
        - ApiKeyAuth: [ApiKeyAuth]
      tags:
        - orc
      requestBody:
        description: Add first and/or last name
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - $ref: "#/components/schemas/FirstNameModel"
                - $ref: "#/components/schemas/LastNameModel"
                - $ref: "#/components/schemas/FirstAndLastNameModel"
            examples:
              first_name:
                $ref: "#/components/examples/FirstName"
              last_name:
                $ref: "#/components/examples/LastName"
              first_and_last_name:
                $ref: "#/components/examples/FirstAndLastName"
      responses:
        "200":
          $ref: "#/components/responses/200PostFirstAndLastName"
        "400":
          $ref: "#/components/responses/400PostInvalidBody"
        "409":
          $ref: "#/components/responses/409PostAlreadyExists"
    get:
      summary: Retrieve a pseudo-random name
      tags:
        - orc
      responses:
        "200":
          $ref: "#/components/responses/200GetFirstAndLastName"
  /skeleton:
    post:
      summary: Add pseudo-random name options
      security:
        - ApiKeyAuth: [ApiKeyAuth]
      tags:
        - skeleton
      requestBody:
        description: Add first and/or last name
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - $ref: "#/components/schemas/FirstNameModel"
                - $ref: "#/components/schemas/LastNameModel"
                - $ref: "#/components/schemas/FirstAndLastNameModel"
            examples:
              first_name:
                $ref: "#/components/examples/FirstName"
              last_name:
                $ref: "#/components/examples/LastName"
              first_and_last_name:
                $ref: "#/components/examples/FirstAndLastName"
      responses:
        "200":
          $ref: "#/components/responses/200PostFirstAndLastName"
        "400":
          $ref: "#/components/responses/400PostInvalidBody"
        "409":
          $ref: "#/components/responses/409PostAlreadyExists"
    get:
      summary: Retrieve a pseudo-random name
      tags:
        - skeleton
      responses:
        "200":
          $ref: "#/components/responses/200GetFirstAndLastName"
  /troll:
    post:
      summary: Add pseudo-random name options
      security:
        - ApiKeyAuth: [ApiKeyAuth]
      tags:
        - troll
      requestBody:
        description: Add first and/or last name
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - $ref: "#/components/schemas/FirstNameModel"
                - $ref: "#/components/schemas/LastNameModel"
                - $ref: "#/components/schemas/FirstAndLastNameModel"
            examples:
              first_name:
                $ref: "#/components/examples/FirstName"
              last_name:
                $ref: "#/components/examples/LastName"
              first_and_last_name:
                $ref: "#/components/examples/FirstAndLastName"
      responses:
        "200":
          $ref: "#/components/responses/200PostFirstAndLastName"
        "400":
          $ref: "#/components/responses/400PostInvalidBody"
        "409":
          $ref: "#/components/responses/409PostAlreadyExists"
    get:
      summary: Retrieve a pseudo-random name
      tags:
        - troll
      responses:
        "200":
          $ref: "#/components/responses/200GetFirstAndLastName"
components:
  examples:
    FirstName:
      summary: Add a new first name
      value:
        first_name: Barnaby
    LastName:
      summary: Add a new last name
      value:
        last_name: The brass dragon
    FirstAndLastName:
      summary: Add a new first and last name
      value:
        first_name: Barnaby
        last_name: The brass dragon
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    ErrorModel:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
        message:
          type: string
    FirstNameModel:
      type: object
      required:
      - first_name
      properties:
        first_name:
          type: string
    LastNameModel:
      type: object
      required:
      - last_name
      properties:
        last_name:
          type: string
    FirstAndLastNameModel:
      type: object
      required:
      - first_name
      - last_name
      properties:
        first_name:
          type: string
        last_name:
          type: string
  responses:
    200GetFirstName:
      description: "Successful response"
      content:
        application/json:
          schema:
            type: object
            required:
            - first_name
            - full_name
            properties:
              first_name:
                type: string
              full_name:
                type: string
    200PostFirstName:
      description: "Successful response"
      content:
        application/json:
          schema:
            type: object
            required:
            - first_name
            - message
            properties:
              first_name:
                type: string
              message:
                type: string
    200GetFirstAndLastName:
      description: "Successful response"
      content:
        application/json:
          schema:
            type: object
            required:
            - first_name
            - last_name
            - full_name
            properties:
              first_name:
                type: string
              last_name:
                type: string
              full_name:
                type: string
    200PostFirstAndLastName:
      description: "Successful response"
      content:
        application/json:
          schema:
            type: object
            required:
            - message
            properties:
              first_name:
                type: string
              last_name:
                type: string
              message:
                type: string
    400PostInvalidBody:
      description: "Invalid body in POST"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorModel"
    409PostAlreadyExists:
      description: "Duplicate record"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorModel"

The section of the YAML before the tags is fairly straight forward, as we’re just assigning metadata and references:

openapi: 3.0.1
info:
  title: Monsternames - OpenAPI 3.0
  description: |-
    This is a relatively simple RESTAPI, based on the OpenAPI 3.0 specification, which generates pseudo-random names for
    common fantasy monsters.
  license:
    name: BSD 3 clause
    url: https://github.com/sudoblark/monsternames.open-api/blob/main/LICENSE.txt
  version: 1.0.11
externalDocs:
  description: Source API definition
  url: https://github.com/sudoblark/monsternames.open-api/
servers:
  - url: https://monsternames-api.com/api/v1.0

The tags section is, again, metadata but this time for OpenAPI itself; it’ll let us group individual operations rather than just present the user with a wall of text:

tags:
  - name: goatmen
    description: Names themed on cute fluffy animals
  - name: goblin
    description: Names themed on washed out wrestlers/average blokes
  - name: ogre
    description: Names themed on cavemen like speech
  - name: orc
    description: Names themed on <noun> + <silly moniker>
  - name: skeleton
    description: Names themed on 18th Century British Gentlemen
  - name: troll
    description: Names themed on a Scandinavian twist

Next we have a series of paths which actually define our API. If we examine the first endpoint we can see what’s going on:

paths:
  /goatmen:
    post:
      summary: Add pseudo-random name options
      security:
        - ApiKeyAuth: [ApiKeyAuth]
      tags:
        - goatmen
      requestBody:
        description: Add first name
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FirstNameModel"
            examples:
              first_name:
                $ref: "#/components/examples/FirstName"
      responses:
        "200":
          $ref: "#/components/responses/200PostFirstName"
        "400":
          $ref: "#/components/responses/400PostInvalidBody"
        "409":
          $ref: "#/components/responses/409PostAlreadyExists"
    get:
      summary: Retrieve a pseudo-random name
      tags:
        - goatmen
      responses:
        "200":
          $ref: "#/components/responses/200GetFirstName"

Here you can see that:

• We define a base path (/goatmen) for the API. This will get combined with the servers.url value to get the full path to the endpoint

• For the endpoint, we’ve defined a post and get method

• For the post method, we:

  • Map through to a securitySchema (more on that later) to require authorisation for this endpoint

  • Use the tag to group this together with other methods

  • Explicitly define the allowed request body

  • Explicitly provide an example of a valid request

  • Explicitly define what responses a user can expect

• Whilst the get method, being simpler, just defines the expected response

Thus, it’s in our components: that we do the heavy lifting. Here we:

• Create reusable examples we can reference in our endpoint definitions, for example:

  examples:
    FirstName:
      summary: Add a new first name
      value:
        first_name: Barnaby

• Define a security schema. This can be used the API/operation level. As per above - we just use it secure the POST endpoints:

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

• Define data models, explicitly defining what data item(s) are required and their types. Which for this example are used across response components and to define allowed arguments within our requests bodies. For example:

  schemas:
    ...
    FirstNameModel:
      type: object
      required:
      - first_name
      properties:
        first_name:
          type: string

• Define response components, allowing us to define a set of common responses across the API and then reference in our endpoint definitions… rather than type it all out by hand every time:

  responses:
    200GetFirstName:
      description: "Successful response"
      content:
        application/json:
          schema:
            type: object
            required:
            - first_name
            - full_name
            properties:
              first_name:
                type: string
              full_name:
                type: string

And that’s it. Those are the basic building blocks of the OpenAPI definition, which we’ve cobbled together to create an explicit definition of what the monsternames-api looks like.

Here we simply create a new API Gateway for all of our methods etc to hang off of.

resource "aws_api_gateway_rest_api" "api_gateway" {
  name        = lower("${var.account}-${var.environment}-${local.service_name}-api-gateway")
  description = "API Gatway for ${local.service_name} in ${var.environment} for ${var.account} - managed by Terraform"
}

Here, the only change is to ensure our policy attachment has the correct syntax to reference the upload policy made as part of a for-each (more on that next)

resource "aws_iam_group" "static_content_upload" {
  name        = "${local.static_bucket_name}-static-content-upload-group"
  path        = "${local.base_path}iam/"
}
resource "aws_iam_group_membership" "static_content_upload" {
  group = aws_iam_group.static_content_upload.id
  name  = "${aws_iam_group.static_content_upload.name}-membership"
  users = var.static_content_upload_users
}
resource "aws_iam_group_policy_attachment" "attachments" {
  group = aws_iam_group.static_content_upload.id
  policy_arn = aws_iam_policy.policies["upload"].arn
}

Here we do two things:

• Refactor the existing policies to be created as part of a for-each to allow ease of management

• Add a new read policy for a new role we’ll create later for the API Gateway to assume… so it can actually read bucket contents

locals {
  iam_policies = {
    "read" = {
      name: "${local.static_bucket_name}-read-policy"
      description: "Policy which allows read access to ${local.static_bucket_name} - managed by Terraform"
      policy: data.aws_iam_policy_document.static_content_read.json
    },
    "upload" = {
      name: "${local.static_bucket_name}-upload-policy"
      description: "Policy which allows upload access to ${local.static_bucket_name} - managed by Terraform"
      policy: data.aws_iam_policy_document.static_content_upload.json
    }
  }
}
data "aws_iam_policy_document" "static_content_upload" {
  statement {
    sid = "1"
    effect = "Allow"
    actions = [
      "s3:ListBucket"
    ]
    resources = [
      "arn:aws:s3:::${aws_s3_bucket.static_content.id}"
    ]
  }
  statement {
    sid = "2"
    effect = "Allow"
    actions = [
      "s3:Put*",
      "s3:Get*",
      "s3:DeleteObject"
    ]
    resources = [
      "arn:aws:s3:::${aws_s3_bucket.static_content.id}/*"
    ]
  }
}
data "aws_iam_policy_document" "static_content_read" {
  statement {
    sid = "1"
    effect = "Allow"
    actions = [
      "s3:ListBucket"
    ]
    resources = [
      "arn:aws:s3:::${aws_s3_bucket.static_content.id}"
    ]
  }
  statement {
    sid = "2"
    effect = "Allow"
    actions = [
      "s3:Get*"
    ]
    resources = [
      "arn:aws:s3:::${aws_s3_bucket.static_content.id}/*"
    ]
  }
}
resource "aws_iam_policy" "policies" {
  for_each = local.iam_policies
  name        = each.value["name"]
  path        = "${local.base_path}iam/"
  description = each.value["description"]
  policy      = each.value["policy"]
  tags = local.default_tags
}

Here we create a new role - ensuring the assumption policy allows the API Gateway to assume it - which will grant the API Gateway read access to the s3 bucket.

Later on we can use this role to fine-tune permissions for lambdas etc if we hang other endpoints off of the gateway.

data "aws_iam_policy_document" "api_gateway_assumption" {
  statement {
    actions = ["sts:AssumeRole"]
    principals {
      type        = "Service"
      identifiers = ["apigateway.amazonaws.com"]
    }
  }
}
resource "aws_iam_role" "api_gateway" {
  name = lower("${var.account}-${var.environment}-${local.service_name}-api-gateway")
  assume_role_policy = data.aws_iam_policy_document.api_gateway_assumption.json
  tags = local.default_tags
}
resource "aws_iam_role_policy_attachment" "api_gateway_read" {
  role       = aws_iam_role.api_gateway.name
  policy_arn = aws_iam_policy.policies["read"].arn
}

This is in effect the meat and potatoes of what we’re trying to achieve. It’s quite verbose, so maybe the visualisation the AWS console provides may help us understand what’s going on:

• The method request is our aws_api_gateway_method and thus defines permissible methods allowed on the resource (in this case the root \ path) and if auth is required or not

• The integration request is our aws_api_gateway_integration and thus defines what the API Gateway should actually do if it received a valid method. In this instance, we’ve:

  • Given the full path to the index.html file in our S3 bucket and told it to GET this item

  • Told the API Gateway to use the IAM role from earlier via the credentials parameter, thus ensuring it assumptions this role to perform the action

• The integration response is our `aws_api_gateway_integration_response` which defines a the response from the integration request we’ve setup, here we’re explicitly defining that the header of Content-Type must be text/html to ensure a browser renders this correctly

• The method response is our aws_api_gateway_method_response which defines a valid response from the integration, here we state that a header of Content-Type must be provided for the 200 response to be valid

resource "aws_api_gateway_method" "swagger_ui" {
  rest_api_id   = aws_api_gateway_rest_api.api_gateway.id
  resource_id   = aws_api_gateway_rest_api.api_gateway.root_resource_id
  http_method   = "GET"
  authorization = "NONE"
}

resource "aws_api_gateway_integration" "swagger_ui" {
  rest_api_id             = aws_api_gateway_rest_api.api_gateway.id
  resource_id             = aws_api_gateway_rest_api.api_gateway.root_resource_id
  http_method             = aws_api_gateway_method.swagger_ui.http_method
  # How the integration will interact with the backend of the resource
  integration_http_method = "GET"
  credentials             = aws_iam_role.api_gateway.arn
  type                    = "AWS"
  # See https://docs.aws.amazon.com/apigateway/api-reference/resource/integration/
  uri                     = "arn:aws:apigateway:${var.aws_region}:s3:path//${aws_s3_bucket.static_content.id}/index.html"
}

resource "aws_api_gateway_method_response" "swagger_ui_200" {
  rest_api_id = aws_api_gateway_rest_api.api_gateway.id
  resource_id = aws_api_gateway_rest_api.api_gateway.root_resource_id
  http_method = aws_api_gateway_method.swagger_ui.http_method
  status_code = "200"

  response_parameters = {
    "method.response.header.Content-Type" = true
  }
}

resource "aws_api_gateway_integration_response" "swagger_ui_200" {
  rest_api_id = aws_api_gateway_rest_api.api_gateway.id
  resource_id = aws_api_gateway_rest_api.api_gateway.root_resource_id
  http_method = aws_api_gateway_method.swagger_ui.http_method
  status_code = "200"

  response_parameters = {
    "method.response.header.Content-Type" = "'text/html'"
  }
}

Here we’re stating that aws_region may be passed through to the module instantiation to define the S3 endpoint that our API Gateway will query.

variable "environment" {
  description = "The environment within which we're instantiating this module."
  type        = string
  validation {
    condition = anytrue([
      var.environment == "Prod",
      var.environment == "Stage",
      var.environment == "Dev"
    ])
    error_message = "Only the following environments are supported: Prod/Stage/Dev"
  }
}
variable "account" {
  description = "The AWS account within which we're instantiating this module."
  type = string
}
variable "static_content_versioning" {
  description = "Whether to enable versioning on the static content S3 bucket."
  type = string
  default = "Enabled"
  validation {
    condition = anytrue([
      var.static_content_versioning == "Enabled",
      var.static_content_versioning == "Suspended",
      var.static_content_versioning == "Disabled"
    ])
    error_message = "Only the following environments are supported: Enabled/Suspended/Disabled"
  }
}
variable "source_repository" {
  description = "Terraform repository managing this module, used for tagging purposes."
  type = string
  default = "terraform.aws"
}
variable "static_content_upload_users" {
  description = "IAM users whom should be allowed to assume static content upload role"
  type = list(string)
  default = []
}
variable "aws_region" {
  description = "The AWS region we are deploying the service into, used for API Gateway routing"
  type = string
  default = "eu-west-2"
  validation {
    condition = contains([
      "eu-west-2"
    ], var.aws_region)
    error_message = format("Invalid region provided, supported regions are as follows:  /%s",
      jsonencode([
        "eu-west-2"
      ]))
  }
}