fix(apigateway): defaultChild on RestApi returns the underlying L1 (#4318)

* fix(apigateway): defaultChild on RestApi returns the underlying L1

Current calls to defaultChild would throw an exception since it
contains children named 'Resource' and 'Default'.
Explicitly setting the defaultChild value to the CfnRestApi construct.

fixes #3234

* Add tests and fixup documentation

* Add period

* PR feedback

Author: nija-at

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

@@ -230,6 +230,7 @@ export class RestApi extends Resource implements IRestApi {
       cloneFrom: props.cloneFrom ? props.cloneFrom.restApiId : undefined,
       parameters: props.parameters
     });
+    this.node.defaultChild = resource;
 
     this.restApiId = resource.ref;
 

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

@@ -2,7 +2,7 @@ import { expect, haveResource, haveResourceLike, ResourcePart } from '@aws-cdk/a
 import { App, CfnElement, CfnResource, Stack } from '@aws-cdk/core';
 import { Test } from 'nodeunit';
 import apigateway = require('../lib');
-import { JsonSchemaType, JsonSchemaVersion } from '../lib';
+import { CfnRestApi, JsonSchemaType, JsonSchemaVersion } from '../lib';
 
 // tslint:disable:max-line-length
 
@@ -100,6 +100,13 @@ export = {
     test.done();
   },
 
+  'defaultChild is set correctly'(test: Test) {
+    const stack = new Stack();
+    const api = new apigateway.RestApi(stack, 'my-api');
+    test.ok(api.node.defaultChild instanceof CfnRestApi);
+    test.done();
+  },
+
   '"name" is defaulted to resource physical name'(test: Test) {
     // GIVEN
     const stack = new Stack();

packages/@aws-cdk/core/lib/construct.ts

@@ -198,7 +198,10 @@ export class ConstructNode {
   }
 
   /**
-   * Returns the child construct that has the id `Default` or `Resource"`
+   * Returns the child construct that has the id `Default` or `Resource"`.
+   * This is usually the construct that provides the bulk of the underlying functionality.
+   * Useful for modifications of the underlying construct that are not avialable at the higher levels.
+   *
    * @throws if there is more than one child
    * @returns a construct or undefined if there is no default child
    */