update README and integ test

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

@@ -5,17 +5,22 @@ import * as integ from '@aws-cdk/integ-tests-alpha';
 const app = new cdk.App();
 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');
 
-// Create a new deployment that uses existing stage
-new apigateway.Deployment(stack, 'MyManualDeployment', {
+// Manually create a deployment that deploys to an existing stage
+const deployment = new apigateway.Deployment(stack, 'MyManualDeployment', {
   api: api,
   stageName: 'myStage',
 });
 
+// Generate a new logical ID so the deployment reflects changes made to api
+deployment.addToLogicalId(`Deployment-${Date.now()}`);
+
 new integ.IntegTest(app, 'restapi-import-deployment-stage', {
   testCases: [stack],
 });

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

@@ -997,19 +997,27 @@ const api = new apigateway.RestApi(this, 'books', {
 ```
 ### Deploying to an existing stage
 
-If you want to use an existing stage for a deployment, you can specify the stage name in the deployment as follows:
+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.
+
+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.
 ```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',
 });
 
+// Generate a new logical ID so the deployment reflects changes made to api
+deployment.addToLogicalId(`Deployment-${Date.now()}`);
+
 ```
 
+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.
 
 ### Deep dive: Invalidation of deployments
 

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

@@ -30,7 +30,9 @@ export interface DeploymentProps {
   /**
    * The name of the stage the API Gateway deployment deploys to.
    *
-   * @default - No stage name.
+   * @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;
 }
@@ -69,10 +71,9 @@ export class Deployment extends Resource {
   /** @attribute */
   public readonly deploymentId: string;
   public readonly api: IRestApi;
-
   /**
-  * The stage of the API Gateway deployment.
-  */
+   * The stage of the API gateway deployment.
+   */
   public readonly stageName?: string;
 
   private readonly resource: LatestDeploymentResource;