feat(apigateway): import an existing Resource (aws#12785)

feat(apigateway): add fromResourceAttribute helper for importing Resource

closes aws#4432

NOTE: No change in Readme is done since I was not able to find a good place for it in the Readme.


----

*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/resource.ts

@@ -373,7 +373,51 @@ export abstract class ResourceBase extends ResourceConstruct implements IResourc
   }
 }
 
+/**
+ * Attributes that can be specified when importing a Resource
+ */
+export interface ResourceAttributes {
+  /**
+   * The ID of the resource.
+   */
+  readonly resourceId: string;
+
+  /**
+   * The rest API that this resource is part of.
+   */
+  readonly restApi: IRestApi;
+
+  /**
+   * The full path of this resource.
+   */
+  readonly path: string;
+}
+
 export class Resource extends ResourceBase {
+  /**
+   * Import an existing resource
+   */
+  public static fromResourceAttributes(scope: Construct, id: string, attrs: ResourceAttributes): IResource {
+    class Import extends ResourceBase {
+      public readonly api = attrs.restApi;
+      public readonly resourceId = attrs.resourceId;
+      public readonly path = attrs.path;
+      public readonly defaultIntegration?: Integration = undefined;
+      public readonly defaultMethodOptions?: MethodOptions = undefined;
+      public readonly defaultCorsPreflightOptions?: CorsOptions = undefined;
+
+      public get parentResource(): IResource {
+        throw new Error('parentResource is not configured for imported resource.');
+      }
+
+      public get restApi(): RestApi {
+        throw new Error('restApi is not configured for imported resource.');
+      }
+    }
+
+    return new Import(scope, id);
+  }
+
   public readonly parentResource?: IResource;
   public readonly api: IRestApi;
   public readonly resourceId: string;

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

@@ -236,6 +236,27 @@ describe('resource', () => {
 
   });
 
+  test('fromResourceAttributes()', () => {
+    // GIVEN
+    const stack = new Stack();
+    const resourceId = 'resource-id';
+    const api = new apigw.RestApi(stack, 'MyRestApi');
+
+    // WHEN
+    const imported = apigw.Resource.fromResourceAttributes(stack, 'imported-resource', {
+      resourceId,
+      restApi: api,
+      path: 'some-path',
+    });
+    imported.addMethod('GET');
+
+    // THEN
+    expect(stack).toHaveResource('AWS::ApiGateway::Method', {
+      HttpMethod: 'GET',
+      ResourceId: resourceId,
+    });
+  });
+
   describe('getResource', () => {
 
     describe('root resource', () => {