terraform-module-aws-apigateway-swagger-ui

Serve Swagger documentation right from your API-Gateway.

Features

• Serve swagger docs right from API-Gateway

Usage

HTTP or REST-API with manual endpoint creation

module "swagger_ui" {
  source  = "timo-reymann/terraform-module-aws-apigateway-swagger-ui"
  version = "1.5.2"

  prefix                     = "my-api-service"
  openapi_definition_content = file("my-definition.yml")
  openapi_definition_format  = "yaml"
  # In case you want to use json:
  # openapi_definition_content = file("my-definition.json")
  # openapi_definition_format  = "json"
  create_api_endpoints       = false
}

In addition you define the endpoints inside your openapi spec.

You can also reuse the output routes to get a reference or even generate it in your openapi template.

HTTP-API with automatic endpoint creation

module "swagger_ui" {
  source  = "timo-reymann/terraform-module-aws-apigateway-swagger-ui"
  version = "1.5.2"

  prefix                     = "my-api-service"
  openapi_definition_content = file("my-definition.yml")
  openapi_definition_format  = "yaml"
  # In case you want to use json:
  # openapi_definition_content = file("my-definition.json")
  # openapi_definition_format  = "json"
}

Now you can access your swagger docs from https://<api-id>.execute-api.<region>.amazonaws.com/swagger-ui.html, this is the same behaviour as with Spring Boot and the Swagger Starter.

In addition you can also use https://<api-id>.execute-api.<region>.amazonaws.com/swagger-ui, if you dont want the entrypoint as a top level shortcut you can also set enable_swagger_ui_entrypoint to false.

Requirements

Name	Version
terraform	>= 1.2.0
archive	> 1
aws	~> 4

Providers

Name	Version
archive	2.2.0
aws	4.48.0

Modules

No modules.

Resources

Name	Type
aws_apigatewayv2_integration.this	resource
aws_apigatewayv2_route.this	resource
aws_cloudwatch_log_group.this	resource
aws_iam_role.this	resource
aws_iam_role_policy.this	resource
aws_lambda_function.this	resource
aws_lambda_layer_version.this	resource
aws_lambda_permission.apigateway	resource
archive_file.layer	data source
aws_caller_identity.this	data source
aws_iam_policy_document.assume_role	data source
aws_iam_policy_document.lambda	data source
aws_partition.this	data source
aws_region.this	data source

Inputs

Name	Description	Type	Default	Required
api_gateway_id	ID of the HTTP API-Gateway	string	null	no
create_api_endpoints	Set this to false to add the endpoints inside your OpenAPI definition or your own terraform code	bool	true	no
create_log_group	Should a log group be created for the lambda	string	true	no
enable_config_endpoint	Enable config endpoint serving json	bool	true	no
enable_swagger_ui_entrypoint	Enable swagger ui top level page to redirect to the swagger ui path allowing you to share a flat link and be consistent with e.g. Spring Boot apps	string	true	no
kms_key_arn	ARN of the KMS key to use	string	null	no
log_group_retention_in_days	Amount of days to keep logs	number	3	no
openapi_definition_content	Content of openapi definition	string	n/a	yes
openapi_definition_format	Format of definition	string	"yaml"	no
prefix	Prefix to append to all resource names created. If not specified the API-Gateway name is used as prefix	string	null	no
stage	Name of the stage, when is not $default, the stage is suffixed for the lambda serving to match the path	string	"$default"	no
swagger_config_endpoint_path	Config endpoint to serve swagger json	string	"/swagger-config"	no
swagger_ui_entrypoint_path	Entrypoint for swagger ui redirect	string	"/swagger-ui.html"	no
swagger_ui_path	Base path for swagger ui	string	"/swagger-ui"	no
tags	Tags to assign to resources created by the module	map(string)	{}	no

Outputs

Name	Description
lambda_execution_arn	Execution ARN for the lambda serving the Swagger UI
log_group_arn	ARN of the log group created for the lambda
routes	Routes that can/should be served by the Swagger UI lambda. If you set create_routes to true, you can ignore this

Documentation

How it works - in a nutshell

• Node.js lambda utilizing express-swagger-ui, bundled with webpack
• OpenAPI specification bundled in lambda layer, therefore available at runtime to lambda
• You provide the OpenAPI spec to your API-Gateway terraform resource and the lambda
• The module registers the according endpoints in your API-Gateway

Contributing

I love your input! I want to make contributing to this project as easy and transparent as possible, whether it's:

• Reporting a bug
• Discussing the current state of the configuration
• Submitting a fix
• Proposing new features
• Becoming a maintainer

To get started please read the Contribution Guidelines.

Development

Requirements

• terraform
• pre-commit

Test

Terraform Module

You need go locally installed to run the tests

1. Login to AWS account
2. Go in ./tests and run go test

Lambda

Also runs in CircleCI

1. Go to ./code
2. Install dependencies: npm i
3. Run npm run test

Update lambda zip package

Since the lambda is stored in the repository to reduce complexity you need to build locally and push the updated artifact:

1. Go in ./code
2. Build in docker container: npm run build