update API Gateway event documentation

docs/providers/aws/events/apigateway.md

@@ -586,7 +586,39 @@ See the [api gateway documentation](https://docs.aws.amazon.com/apigateway/lates
 **Notes:**
 
 - A missing/empty request Content-Type is considered to be the API Gateway default (`application/json`)
-- API Gateway docs refer to "WHEN_NO_TEMPLATE" (singular), but this will fail during creation as the actual value should be "WHEN_NO_TEMPLATES" (plural)
+    - [[Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/aws/events/apigateway)](#read-this-on-the-main-serverless-docs-sitehttpswwwserverlesscomframeworkdocsprovidersawseventsapigateway)
+    - [[Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/aws/events/apigateway)](#read-this-on-the-main-serverless-docs-sitehttpswwwserverlesscomframeworkdocsprovidersawseventsapigateway)
+    - [[Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/aws/events/apigateway)](#read-this-on-the-main-serverless-docs-sitehttpswwwserverlesscomframeworkdocsprovidersawseventsapigateway)
+    - [[Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/aws/events/apigateway)](#read-this-on-the-main-serverless-docs-sitehttpswwwserverlesscomframeworkdocsprovidersawseventsapigateway)
+    - [[Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/aws/events/apigateway)](#read-this-on-the-main-serverless-docs-sitehttpswwwserverlesscomframeworkdocsprovidersawseventsapigateway)
+    - [[Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/aws/events/apigateway)](#read-this-on-the-main-serverless-docs-sitehttpswwwserverlesscomframeworkdocsprovidersawseventsapigateway)
+    - [[Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/aws/events/apigateway)](#read-this-on-the-main-serverless-docs-sitehttpswwwserverlesscomframeworkdocsprovidersawseventsapigateway)
+- [API Gateway](#api-gateway)
+  - [Lambda Proxy Integration](#lambda-proxy-integration)
+    - [Simple HTTP Endpoint](#simple-http-endpoint)
+    - [Example "LAMBDA-PROXY" event (default)](#example-lambda-proxy-event-default)
+    - [HTTP Endpoint with Extended Options](#http-endpoint-with-extended-options)
+    - [Enabling CORS](#enabling-cors)
+    - [HTTP Endpoints with `AWS_IAM` Authorizers](#http-endpoints-with-awsiam-authorizers)
+    - [HTTP Endpoints with Custom Authorizers](#http-endpoints-with-custom-authorizers)
+    - [Catching Exceptions In Your Lambda Function](#catching-exceptions-in-your-lambda-function)
+    - [Setting API keys for your Rest API](#setting-api-keys-for-your-rest-api)
+    - [Request Parameters](#request-parameters)
+  - [Lambda Integration](#lambda-integration)
+    - [Example "LAMBDA" event (before customization)](#example-lambda-event-before-customization)
+    - [Request templates](#request-templates)
+      - [Default Request Templates](#default-request-templates)
+      - [Custom Request Templates](#custom-request-templates)
+      - [Pass Through Behavior](#pass-through-behavior)
+    - [Responses](#responses)
+      - [Custom Response Headers](#custom-response-headers)
+    - [Custom Response Templates](#custom-response-templates)
+    - [Status codes](#status-codes)
+      - [Available Status Codes](#available-status-codes)
+      - [Using Status Codes](#using-status-codes)
+      - [Custom Status Codes](#custom-status-codes)
+  - [Setting an HTTP Proxy on API Gateway](#setting-an-http-proxy-on-api-gateway)
+  - [Share API Gateway and API Resources](#share-api-gateway-and-api-resources)
 
 ### Responses
 
@@ -773,3 +805,116 @@ endpoint of your proxy, and the URI you want to set a proxy to.
 
 Now that you have these two CloudFormation templates defined in your `serverless.yml` file, you can simply run
 `serverless deploy` and that will deploy these custom resources for you along with your service and set up a proxy on your Rest API.
+
+## Share API Gateway and API Resources
+
+As you application grows, you will have idea to break it out into multiple services. However, each serverless project generates new API Gateway by default. If you want to share same API Gateway for muliple projects, you 'll need to reference REST API ID and Root Resource ID into serverless.yml files
+
+```yml
+service: service-name
+provider: 
+  name: aws
+  apiGateway:
+    restApiId: xxxxxxxxxx # REST API resource ID. Default is generated by the framework
+    restApiRootResourceId: xxxxxxxxxx # Root resource, represent as / path
+
+functions:
+  ...
+
+```
+
+In case the application has many chilren and grandchildren paths, you also want to break them out into smaller services. 
+
+```yml
+service: service-a
+provider: 
+  apiGateway:
+    restApiId: xxxxxxxxxx 
+    restApiRootResourceId: xxxxxxxxxx
+
+functions:
+  create:
+    handler: posts.create
+    events:
+      - http:
+          method: post
+          path: /posts
+```
+
+```yml
+service: service-b
+provider: 
+  apiGateway:
+    restApiId: xxxxxxxxxx 
+    restApiRootResourceId: xxxxxxxxxx 
+
+functions:
+  create:
+    handler: posts.createComment
+    events:
+      - http:
+          method: post
+          path: /posts/{id}/comments
+```
+
+They reference the same parent path `/posts`. Cloudformation will throw error if we try to generate existed one. To avoid that, we must reference source ID of `/posts`.
+
+```yml
+service: service-a
+provider: 
+  apiGateway:
+    restApiId: xxxxxxxxxx 
+    restApiRootResourceId: xxxxxxxxxx
+    restApiResources:
+      /posts: xxxxxxxxxx
+      
+functions:
+  ...
+
+```
+
+```yml
+service: service-b
+provider: 
+  apiGateway:
+    restApiId: xxxxxxxxxx 
+    restApiRootResourceId: xxxxxxxxxx 
+    restApiResources:
+      /posts: xxxxxxxxxx
+
+functions:
+  ...
+
+```
+
+You can define more than one path resource. Otherwise, serverless will generate paths from root resource. `restApiRootResourceId` can be optional if there isn't path that need to be generated from the root
+
+```yml
+service: service-a
+provider: 
+  apiGateway:
+    restApiId: xxxxxxxxxx 
+    # restApiRootResourceId: xxxxxxxxxx # Optional
+    restApiResources:
+      /posts: xxxxxxxxxx
+      /categories: xxxxxxxxx
+      
+
+functions:
+  listPosts:
+    handler: posts.list
+    events:
+      - http:
+          method: get
+          path: /posts
+
+  listCategories:
+    handler: categories.list
+    events:
+      - http:
+          method: get
+          path: /categories
+
+```
+
+For best practice and CI, CD friendly, we should define Cloudformation resources from early service, then use Cross-Stack References for another ones.

docs/providers/aws/guide/serverless.yml.md

@@ -43,9 +43,9 @@ provider:
     - myFirstKey
     - ${opt:stage}-myFirstKey
     - ${env:MY_API_KEY} # you can hide it in a serverless variable
-  apiGateway:
+  apiGateway: # Optional API Gateway global config
     restApiId: xxxxxxxxxx # REST API resource ID. Default is generated by the framework
-    restApiRootResourceId: xxxxxxxxxx # Root resource ID of above REST API
+    restApiRootResourceId: xxxxxxxxxx # Root resource ID, represent as / path
     restApiResources: # List of existing resources that were created in the REST API. This is required or the stack will be conflicted
       '/users': xxxxxxxxxx
       '/users/create': xxxxxxxxxx