From 3d968afe0f3cb042254bec202bc7a31f0650827a Mon Sep 17 00:00:00 2001
From: Graham Davison <gdavison@hashicorp.com>
Date: Fri, 8 Nov 2024 11:44:03 -0800
Subject: [PATCH] Adds warnings that `stage_description` and `canary_settings`
 have no effect when `stage_name` isn't set

---
 internal/service/apigateway/deployment.go     | 27 +++++++++++++++++++
 .../r/api_gateway_deployment.html.markdown    |  2 ++
 2 files changed, 29 insertions(+)

diff --git a/internal/service/apigateway/deployment.go b/internal/service/apigateway/deployment.go
index f731ddddbf2..1a101fba8fe 100644
--- a/internal/service/apigateway/deployment.go
+++ b/internal/service/apigateway/deployment.go
@@ -14,6 +14,7 @@ import (
 	"github.com/aws/aws-sdk-go-v2/aws/arn"
 	"github.com/aws/aws-sdk-go-v2/service/apigateway"
 	"github.com/aws/aws-sdk-go-v2/service/apigateway/types"
+	"github.com/hashicorp/go-cty/cty"
 	"github.com/hashicorp/terraform-plugin-sdk/v2/diag"
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry"
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
@@ -124,8 +125,23 @@ func resourceDeploymentCreate(ctx context.Context, d *schema.ResourceData, meta
 		Variables:        flex.ExpandStringValueMap(d.Get("variables").(map[string]interface{})),
 	}
 
+	_, hasStageName := d.GetOk("stage_name")
+
+	if _, ok := d.GetOk("stage_description"); !hasStageName && ok {
+		diags = append(diags, noEffectWithoutWarningDiag(
+			cty.GetAttrPath("stage_description"),
+			cty.GetAttrPath("stage_name"),
+		))
+	}
+
 	if v, ok := d.GetOk("canary_settings"); ok && len(v.([]interface{})) > 0 && v.([]interface{})[0] != nil {
 		input.CanarySettings = expandDeploymentCanarySettings(v.([]interface{})[0].(map[string]interface{}))
+		if !hasStageName {
+			diags = append(diags, noEffectWithoutWarningDiag(
+				cty.GetAttrPath("canary_settings"),
+				cty.GetAttrPath("stage_name"),
+			))
+		}
 	}
 
 	deployment, err := conn.CreateDeployment(ctx, input)
@@ -330,3 +346,14 @@ func expandDeploymentCanarySettings(tfMap map[string]interface{}) *types.Deploym
 
 	return apiObject
 }
+
+func noEffectWithoutWarningDiag(path, otherPath cty.Path) diag.Diagnostic {
+	return errs.NewAttributeWarningDiagnostic(
+		path,
+		"Invalid Attribute Combination",
+		fmt.Sprintf("Attribute %q has no effect when %q is not set.",
+			errs.PathString(path),
+			errs.PathString(otherPath),
+		),
+	)
+}
diff --git a/website/docs/r/api_gateway_deployment.html.markdown b/website/docs/r/api_gateway_deployment.html.markdown
index eb8fb776365..e75e98fee02 100644
--- a/website/docs/r/api_gateway_deployment.html.markdown
+++ b/website/docs/r/api_gateway_deployment.html.markdown
@@ -132,9 +132,11 @@ This resource supports the following arguments:
 
 * `canary_settings` - (Optional, **Deprecated** Use an explicit [`aws_api_gateway_stage` resource](api_gateway_stage.html) instead) Input configuration for the canary deployment when the deployment is a canary release deployment.
   See [`canary_settings](#canary_settings-argument-reference) below.
+  Has no effect when `stage_name` is not set.
 * `description` - (Optional) Description of the deployment
 * `rest_api_id` - (Required) REST API identifier.
 * `stage_description` - (Optional, **Deprecated** Use an explicit [`aws_api_gateway_stage` resource](api_gateway_stage.html) instead) Description to set on the stage managed by the `stage_name` argument.
+  Has no effect when `stage_name` is not set.
 * `stage_name` - (Optional, **Deprecated** Use an explicit [`aws_api_gateway_stage` resource](api_gateway_stage.html) instead) Name of the stage to create with this deployment.
   If the specified stage already exists, it will be updated to point to the new deployment.
   We recommend using the [`aws_api_gateway_stage` resource](api_gateway_stage.html) instead to manage stages.