Introduce intermediary stage to allow proper resource recreation

Unfortunately the current setup still has the issue that prevents us from replacing the API-GW resources when the Swagger file changes.

Fortunately someone else has chimed in with their solution, and this seemed to work during my tests:
hashicorp/terraform#6613 (comment)

Also changed the output of the module to reflect custom domains.

(My test case was only about changing the description variable of the API Gateway module, which affects the Swagger file.)

modules/apigateway/main.tf

@@ -69,16 +69,19 @@ resource "aws_api_gateway_rest_api" "api" {
   description = "${var.description} (stage: ${var.stage})"
 }
 
-resource "aws_api_gateway_deployment" "stage" {
-  depends_on = ["aws_api_gateway_rest_api.api"]
-
+resource "aws_api_gateway_deployment" "deployment" {
   rest_api_id = "${aws_api_gateway_rest_api.api.id}"
-  stage_name  = "${var.stage}"
+  stage_name  = "${var.stage}_deploy"
 
   variables = {
     "version" = "${md5(data.template_file.swagger_file.rendered)}"
   }
+}
 
+resource "aws_api_gateway_stage" "stage" {
+  stage_name = "${var.stage}"
+  rest_api_id = "${aws_api_gateway_rest_api.api.id}"
+  deployment_id = "${aws_api_gateway_deployment.deployment.id}"
 }
 
 data "aws_acm_certificate" "ssl_cert" {
@@ -99,7 +102,7 @@ resource "aws_api_gateway_base_path_mapping" "basepath" {
   count = "${var.enable_custom_domain}"
 
   api_id      = "${aws_api_gateway_rest_api.api.id}"
-  stage_name  = "${aws_api_gateway_deployment.stage.stage_name}"
+  stage_name  = "${aws_api_gateway_stage.stage.stage_name}"
   domain_name = "${aws_api_gateway_domain_name.domain.domain_name}"
   base_path   = "${var.base_path}"
 }

modules/apigateway/outputs.tf

@@ -2,5 +2,8 @@ output "api_id" {
   value = "${aws_api_gateway_rest_api.api.id}"
 }
 output "invoke_url" {
-  value = "${aws_api_gateway_deployment.stage.invoke_url}"
+  # If we have a custom domain set up, we should point the endpoint to that.
+  # Otherwise take the deployment's invoke URL, and strip the intermediary
+  # stage suffix from the URL.
+  value = "${var.enable_custom_domain ? format("https://%s", var.custom_domain) : replace(aws_api_gateway_deployment.deployment.invoke_url, "_deploy", "")}"
 }