chore(apigateway): minor cors followups

packages/@aws-cdk/aws-apigateway/README.md

@@ -474,7 +474,18 @@ running at one origin, access to selected resources from a different origin. A
 web application executes a cross-origin HTTP request when it requests a resource
 that has a different origin (domain, protocol, or port) from its own.
 
-You can add the CORS [preflight](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Preflighted_requests) OPTIONS HTTP method to any API resource via the `addCorsPreflight` method.
+You can add the CORS [preflight](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Preflighted_requests) OPTIONS HTTP method to any API resource via the `defaultCorsPreflightOptions` option or by calling the `addCorsPreflight` on a specific resource.
+
+The following example will enable CORS for all methods and all origins on all resources of the API:
+
+```ts
+new apigateway.RestApi(this, 'api', {
+  defaultCorsPreflightOptions: {
+    allowOrigins: apigateway.Cors.ALL_ORIGINS,
+    allowMethods: apigateway.Cors.ALL_METHODS // this is also the default
+  }
+})
+```
 
 The following example will add an OPTIONS method to the `myResource` API resource, which
 only allows GET and PUT HTTP requests from the origin https://amazon.com.
@@ -490,22 +501,7 @@ See the
 [`CorsOptions`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-apigateway.CorsOptions.html)
 API reference for a detailed list of supported configuration options.
 
-You can specify default options for all resources within an API or a sub-tree using
-`defaultCorsPreflightOptions`:
-
-
-```ts
-new apigateway.RestApi(this, 'api', {
-  defaultCorsPreflightOptions: {
-    allowOrigins: [ 'https://amazon.com' ]
-  }
-});
-```
-
-This means that the construct will add a CORS preflight OPTIONS method to
-**all** HTTP resources in this API gateway.
-
-Similarly, you can specify this at the resource level:
+You can specify defaults this at the resource level, in which case they will be applied to the entire resource sub-tree:
 
 ```ts
 const subtree = resource.addResource('subtree', {

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

@@ -10,10 +10,13 @@ export interface CorsOptions {
   readonly statusCode?: number;
 
   /**
-   * The Access-Control-Allow-Origin response header indicates whether the
-   * response can be shared with requesting code from the given origin.
+   * Specifies the list of origins that are allowed to make requests to this
+   * resource. If you wish to allow all origins, specify `Cors.ALL_ORIGINS` or
+   * `[ * ]`.
    *
-   * Specifies the list of origins that are allowed to make requests to this resource.
+   * Responses will include the `Access-Control-Allow-Origin` response header.
+   * If `Cors.ALL_ORIGINS` is specified, the `Vary: Origin` response header will
+   * also be included.
    *
    * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin
    */
@@ -98,8 +101,16 @@ export class Cors {
    */
   public static readonly ALL_METHODS = ALL_METHODS;
 
+  /**
+   * All origins.
+   */
+  public static readonly ALL_ORIGINS = [ '*' ];
+
   /**
    * The set of default headers allowed for CORS and useful for API Gateway.
    */
   public static readonly DEFAULT_HEADERS = [ 'Content-Type', 'X-Amz-Date', 'Authorization', 'X-Api-Key', 'X-Amz-Security-Token', 'X-Amz-User-Agent' ];
+
+  // utility class
+  private constructor() { }
 }

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

@@ -105,6 +105,8 @@ export interface IResource extends IResourceBase {
    * own.
    *
    * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
+   * @param options CORS options
+   * @returns a `Method` object
    */
   addCorsPreflight(options: CorsOptions): Method;
 }

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

@@ -2,6 +2,7 @@ import { countResources, expect, haveResource } from '@aws-cdk/assert';
 import { Duration, Stack } from '@aws-cdk/core';
 import { Test } from 'nodeunit';
 import apigw = require('../lib');
+import { Cors } from '../lib';
 
 export = {
   'adds an OPTIONS method to a resource'(test: Test) {
@@ -554,7 +555,7 @@ export = {
     // WHEN
     api.root.addResource('AllowAll', {
       defaultCorsPreflightOptions: {
-        allowOrigins: [ '*' ]
+        allowOrigins: Cors.ALL_ORIGINS
       }
     });