Update readme and revert to stageName property

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": {
+  "MyManualDeployment92F2175C6f3141cef1e8fea8ab3b3b8bc90df36d": {
    "Type": "AWS::ApiGateway::Deployment",
    "Properties": {
     "RestApiId": {

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

@@ -7,20 +7,16 @@ 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', {
+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

@@ -270,7 +270,7 @@ The following example uses sets up two Resources '/pets' and '/books' in separat
 > **Warning:** In the code above, an API Gateway deployment is created during the initial CDK deployment.
 However, if there are changes to the resources in subsequent CDK deployments, a new API Gateway deployment is not
 automatically created. As a result, the latest state of the resources is not reflected. To ensure the latest state
-of the resources is reflected, a manual deployment of the API Gateway is required after the CDK deployment.
+of the resources is reflected, a manual deployment of the API Gateway is required after the CDK deployment. See [Controlled triggering of deployments](#controlled-triggering-of-deployments) for more info.
 
 ## Integration Targets
 
@@ -941,7 +941,7 @@ Instructions for configuring your trust store can be found [here](https://aws.am
 By default, the `RestApi` construct will automatically create an API Gateway
 [Deployment] and a "prod" [Stage] which represent the API configuration you
 defined in your CDK app. This means that when you deploy your app, your API will
-be have open access from the internet via the stage URL.
+have open access from the internet via the stage URL.
 
 The URL of your API can be obtained from the attribute `restApi.url`, and is
 also exported as an `Output` from your stack, so it's printed when you `cdk
@@ -1004,7 +1004,7 @@ const api = new apigateway.RestApi(this, 'books', {
 
 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.
+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. If you update the `stageName` property, you should be triggering a new deployment (i.e. with an updated logical ID). To ensure your deployment reflects changes to the `RestApi` model, see [Controlled triggering of deployments](#controlled-triggering-of-deployments).
 ```ts
 const restApi = new apigateway.RestApi(this, 'my-api', {
   deploy: false,
@@ -1014,16 +1014,28 @@ const restApi = new apigateway.RestApi(this, 'my-api', {
 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()}`);
-
 ```
 
 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.
 
+### Controlled triggering of deployments
+
+By default, the `RestApi` construct deploys changes immediately. If you want to
+control when deployments happen, set `{ deploy: false }` and create a `Deployment` construct yourself. Add a revision counter to the construct ID, and update it in your source code whenever you want to trigger a new deployment:
+```ts
+const restApi = new apigateway.RestApi(this, 'my-api', {
+  deploy: false,
+});
+
+const deploymentRevision = 5; // Bump this counter to trigger a new deployment
+new apigateway.Deployment(this, `Deployment${deploymentRevision}`, {
+  api: restApi
+});
+```
+
 ### Deep dive: Invalidation of deployments
 
 API Gateway deployments are an immutable snapshot of the API. This means that we