Describe the feature

Ability to specify existent environments name when creating a new deployment for an API Gateway.

Currently is possible to do that bypassing cdk lib type definition using the suggestion specified here https://stackoverflow.com/questions/63950199/how-to-use-an-existing-stage-in-api-gateway-deployments-in-aws-cdk

const deployment = new apigateway.Deployment(this, "Deployment", {
      api: restApi,
    });
    //deploys an existent stage (dev, stage, prod) - 
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    (deployment as any).resource.stageName = "myStage";
    

See more information here: https://stackoverflow.com/questions/63950199/how-to-use-an-existing-stage-in-api-gateway-deployments-in-aws-cdkenvironment

Use Case

When you have a central API Gateway and multiple other APIs/resources defined in other stacks/repo, we want to be able to deploy it to an "existent" stage without having to create/replace a new one.

1. I have a central API Gateway which has multiple resources:
   • /resource-A -> points to an external resources defined by an external Stack-A
   • /resource-B -> points to an external resources defined by an external Stack-B.

I want to be able to re deploy Stack-A and Stack-B and also create a new deployment for an existent environment - the current options on CDK Constructs doesn't allow to easily do that and suggest creating a new stage by using new Stage
as define here https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.Deployment.html.

Proposed Solution

A property in the deployment construct to use an existent schema (either by stageName or an IStage interface)

 const deployment = new apigateway.Deployment(this, "Deployment", {
      api: restApi,
     stageName: stageName // this extra property to utilize an existent stage 
    });
    

This is the current way of doing that and I can confirm it works:

   (deployment as any).resource.stageName = "myStage";
   

I also considered trying to assign a stage to the rest api construct, but the deployment Stage expects a Stage object and doesn't not accept IStage.

  restApi.deploymentStage = apigateway.Stage.fromStageAttributes(
     this,
     "sggg",
     {
       restApi,
       stageName: "myStage",
     }
   );

Other Information

No response

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

CDK version used

"aws-cdk-lib": "^2.42.1",

Environment details (OS name and version, etc.)

MacOS