feat(apigateway): Add stage ARN attribute (aws#18170)

This adds an attribute to retrieve the resource ARN of a stage (not the
execute-api ARN). This is useful when integrating with services such as
WAF or when writing IAM policies for managing the API.

ARNs for v1 REST APIs are at https://docs.aws.amazon.com/apigateway/latest/developerguide/arn-format-reference.html#apigateway-v1-arns

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/@aws-cdk/aws-apigateway/lib/stage.ts

@@ -1,4 +1,4 @@
-import { Duration, IResource, Resource, Stack, Token } from '@aws-cdk/core';
+import { ArnFormat, Duration, IResource, Resource, Stack, Token } from '@aws-cdk/core';
 import { Construct } from 'constructs';
 import { AccessLogFormat, IAccessLogDestination } from './access-log';
 import { CfnStage } from './apigateway.generated';
@@ -273,6 +273,26 @@ export class Stage extends Resource implements IStage {
     return `https://${this.restApi.restApiId}.execute-api.${Stack.of(this).region}.${Stack.of(this).urlSuffix}/${this.stageName}${path}`;
   }
 
+  /**
+   * Returns the resource ARN for this stage:
+   *
+   *   arn:aws:apigateway:{region}::/restapis/{restApiId}/stages/{stageName}
+   *
+   * Note that this is separate from the execute-api ARN for methods and resources
+   * within this stage.
+   *
+   * @attribute
+   */
+  public get stageArn() {
+    return Stack.of(this).formatArn({
+      arnFormat: ArnFormat.SLASH_RESOURCE_SLASH_RESOURCE_NAME,
+      service: 'apigateway',
+      account: '',
+      resource: 'restapis',
+      resourceName: `${this.restApi.restApiId}/stages/${this.stageName}`,
+    });
+  }
+
   private renderMethodSettings(props: StageProps): CfnStage.MethodSettingProperty[] | undefined {
     const settings = new Array<CfnStage.MethodSettingProperty>();
     const self = this;

packages/@aws-cdk/aws-apigateway/test/stage.test.ts

@@ -113,6 +113,38 @@ describe('stage', () => {
     });
   });
 
+  test('"stageResourceArn" returns the ARN for the stage', () => {
+    // GIVEN
+    const stack = new cdk.Stack();
+    const api = new apigateway.RestApi(stack, 'test-api');
+    const deployment = new apigateway.Deployment(stack, 'test-deploymnet', {
+      api,
+    });
+    api.root.addMethod('GET');
+
+    // WHEN
+    const stage = new apigateway.Stage(stack, 'test-stage', {
+      deployment,
+    });
+
+    // THEN
+    expect(stack.resolve(stage.stageArn)).toEqual({
+      'Fn::Join': [
+        '',
+        [
+          'arn:',
+          { Ref: 'AWS::Partition' },
+          ':apigateway:',
+          { Ref: 'AWS::Region' },
+          '::/restapis/',
+          { Ref: 'testapiD6451F70' },
+          '/stages/',
+          { Ref: 'teststage8788861E' },
+        ],
+      ],
+    });
+  });
+
   test('custom method settings can be set by their path', () => {
     // GIVEN
     const stack = new cdk.Stack();