Refactor deploying to existing stage using function

packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.js.snapshot/integtest-restapi-import-deployment-stage.template.json

@@ -25,7 +25,7 @@
     }
    }
   },
-  "MyManualDeployment92F2175C35a2644115e0765ad867f11b599a51c1": {
+  "MyManualDeployment92F2175Ccc11cdc8066f1062a899dd200fc12825": {
    "Type": "AWS::ApiGateway::Deployment",
    "Properties": {
     "RestApiId": {
@@ -35,7 +35,9 @@
    },
    "DependsOn": [
     "myapiGETF990CE3C"
-   ]
+   ],
+   "UpdateReplacePolicy": "Retain",
+   "DeletionPolicy": "Retain"
   }
  },
  "Parameters": {

packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.ts

@@ -7,19 +7,19 @@ const stack = new cdk.Stack(app, 'integtest-restapi-import-deployment-stage');
 
 // Set deploy to false so RestApi does not automatically create a Deployment
 const api = new apigateway.RestApi(stack, 'my-api', {
-  retainDeployments: true,
   deploy: false,
 });
 api.root.addMethod('GET');
 
 // Manually create a deployment that deploys to an existing stage
 const deployment = new apigateway.Deployment(stack, 'MyManualDeployment', {
   api: api,
-  stageName: 'myStage',
+  retainDeployments: true,
 });
 
-// Generate a new logical ID so the deployment reflects changes made to api
-deployment.addToLogicalId(`Deployment-${Date.now()}`);
+// Deploy to a stage that already exists in the account
+// Here we are assuming the account has a stage named 'myStage'
+deployment.deployToExistingStage('myStage');
 
 new integ.IntegTest(app, 'restapi-import-deployment-stage', {
   testCases: [stack],

packages/aws-cdk-lib/aws-apigateway/README.md

@@ -1002,27 +1002,28 @@ const api = new apigateway.RestApi(this, 'books', {
 ```
 ### Deploying to an existing stage
 
-If you want to use an existing stage for a deployment, first set `{ deploy: false }` so that `RestApi` does not automatically create new `Deployment` and `Stage` resources.  Then you can manually define a `apigateway.Deployment` resource and specify the stage name for your existing stage using the `stageName` property.
+If you want to use an existing stage for a deployment, first set `{ deploy: false }` so that `RestApi` does not automatically create new `Deployment` and `Stage` resources.  Then you can manually define a `apigateway.Deployment` resource and use the `deployToExistingStage()` method to specify the stage name and create a new deployment to the stage.
 
-Note that as long as the deployment's logical ID doesn't change, it will represent the snapshot in time when the resource was created. To ensure your deployment reflects changes to the `RestApi` model, use the method `addToLogicalId(data)` to augment the logical ID generated for the deployment resource.
+Note that as long as the deployment's logical ID doesn't change, it will represent the snapshot in time when the resource was created. The `deployToExistingStage()` method calls `addToLogicalId()` with a timestamp to create a new `Deployment` resource. This ensures your deployment reflects the latest changes to the `RestApi` model. 
+
+By default, the previous deployment will be deleted because of the logical ID update. If you wish to retain old deployment resources when the API changes, set the `retainDeployments` property to `true`.
 ```ts
 const restApi = new apigateway.RestApi(this, 'my-api', {
   deploy: false,
 });
 
-// Use `stageName` to deploy to an existing stage
 const deployment = new apigateway.Deployment(this, 'my-deployment', {
   api: restApi,
-  stageName: 'dev',
+  retainDeployments: true // keep old deployments
 });
 
-// Generate a new logical ID so the deployment reflects changes made to api
-deployment.addToLogicalId(`Deployment-${Date.now()}`);
+// Deploy latest RestApi changes to an existing stage
+deployment.deployToExistingStage('dev');
 
 ```
 
-If the `stageName` property is set but a stage with the corresponding name does not exist, a new stage 
-resource will be created with the provided stage name.
+If `deployToExistingStage()` is called with a stage name that does not correspond to an existing stage,
+a new stage resource will be created with the provided stage name.
 
 ### Deep dive: Invalidation of deployments
 

packages/aws-cdk-lib/aws-apigateway/lib/deployment.ts

@@ -26,15 +26,6 @@ export interface DeploymentProps {
    * @default false
    */
   readonly retainDeployments?: boolean;
-
-  /**
-   * The name of the stage the API Gateway deployment deploys to.
-   *
-   * @default - No stage name. If the `stageName` property is set but a stage with the
-   * corresponding name does not exist, a new stage resource will be created with the
-   * provided stage name.
-   */
-  readonly stageName?: string;
 }
 
 /**
@@ -71,10 +62,6 @@ export class Deployment extends Resource {
   /** @attribute */
   public readonly deploymentId: string;
   public readonly api: IRestApi;
-  /**
-   * The stage of the API gateway deployment.
-   */
-  public readonly stageName?: string;
 
   private readonly resource: LatestDeploymentResource;
 
@@ -84,7 +71,6 @@ export class Deployment extends Resource {
     this.resource = new LatestDeploymentResource(this, 'Resource', {
       description: props.description,
       restApi: props.api,
-      stageName: props.stageName,
     });
 
     if (props.retainDeployments) {
@@ -135,6 +121,18 @@ export class Deployment extends Resource {
     // dependencies between the underlying CfnResources.
     this.node.addDependency(method.node.defaultChild as CfnResource);
   }
+
+  /**
+   * Deploy to an existing stage. Updates the logical ID of this Deployment resource
+   * so it will always create a new deployment and reflect the latest API changes.
+   * If this Deployment resource does not have `retainDeployments` set to `true`,
+   * calling this method will delete the old deployment resource.
+   * @param stageName The name of the stage
+   */
+  public deployToExistingStage(stageName: string) {
+    this.resource.stageName = stageName;
+    this.resource.addToLogicalId(new Date().getTime());
+  }
 }
 
 interface LatestDeploymentResourceProps {