Add documentation for Shared API Gateway

Author: vlewin

README.md

@@ -169,6 +169,40 @@ stepFunctions:
       definition:
 ```
 
+#### [Share API Gateway and API Resources](https://serverless.com/framework/docs/providers/aws/events/apigateway/#share-api-gateway-and-api-resources)
+
+You can share the same API Gateway between multiple projects by referencing its REST API ID and Root Resource ID in serverless.yml as follows:
+
+```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:
+  ...
+```
+If your application has many nested paths, you might also want to break them out into smaller services.
+
+However, Cloudformation will throw an error if we try to generate an existing path resource. To avoid that, we reference the resource ID:
+
+```yml
+service: service-a
+provider:
+  apiGateway:
+    restApiId: xxxxxxxxxx
+    restApiRootResourceId: xxxxxxxxxx
+    restApiResources: # List of existing resources that were created in the REST API. This is required or the stack will be conflicted
+
+      /posts: xxxxxxxxxx
+
+functions:
+  ...
+```
+
+
 #### Enabling CORS
 
 To set CORS configurations for your HTTP endpoints, simply modify your event configurations as follows: