docs: update README with request schema validators

Author: paolorossig

README.md

@@ -38,6 +38,7 @@ Serverless Framework v2.32.0 or later is required.
          - [Customizing response headers and templates](#customizing-response-headers-and-templates)
          - [Send request to an API](#send-request-to-an-api)
          - [Setting API keys for your Rest API](#setting-api-keys-for-your-rest-api)
+         - [Request Schema Validators](#request-schema-validators)
      - [Schedule](#schedule)
          - [Enabling / Disabling](#enabling--disabling)
          - [Specify Name and Description](#specify-name-and-description)
@@ -933,6 +934,88 @@ Please note that those are the API keys names, not the actual values. Once you d
 
 Clients connecting to this Rest API will then need to set any of these API keys values in the x-api-key header of their request. This is only necessary for functions where the private property is set to true.
 
+#### Request Schema Validators
+
+To use [request schema validation](https://serverless.com/framework/docs/providers/aws/events/apigateway/#request-schema-validators) with API gateway, add the [JSON Schema](https://json-schema.org/) for your content type. Since JSON Schema is represented in JSON, it's easier to include it from a file.
+
+```yaml
+stepFunctions:
+  stateMachines:
+    create:
+      events:
+        - http:
+            path: posts/create
+            method: post
+            request:
+              schemas:
+                application/json: ${file(create_request.json)}
+```
+
+In addition, you can also customize created model with name and description properties.
+
+```yaml
+stepFunctions:
+  stateMachines:
+    create:
+      events:
+        - http:
+            path: posts/create
+            method: post
+            request:
+              schemas:
+                application/json:
+                  schema: ${file(create_request.json)}
+                  name: PostCreateModel
+                  description: 'Validation model for Creating Posts'
+```
+
+To reuse the same model across different events, you can define global models on provider level. In order to define global model you need to add its configuration to `provider.apiGateway.request.schemas`. After defining a global model, you can use it in the event by referencing it by the key. Provider models are created for application/json content type.
+
+```yaml
+provider:
+    ...
+    apiGateway:
+      request:
+        schemas:
+          post-create-model:
+            name: PostCreateModel
+            schema: ${file(api_schema/post_add_schema.json)}
+            description: "A Model validation for adding posts"
+ 
+stepFunctions:
+  stateMachines:
+    create:
+      events:
+        - http:
+            path: posts/create
+            method: post
+            request:
+              schemas:
+                application/json: post-create-model
+```
+
+A sample schema contained in `create_request.json` might look something like this:
+
+```json
+{
+  "definitions": {},
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "title": "The Root Schema",
+  "required": ["username"],
+  "properties": {
+    "username": {
+      "type": "string",
+      "title": "The Foo Schema",
+      "default": "",
+      "pattern": "^[a-zA-Z0-9]+$"
+    }
+  }
+}
+```
+
+**NOTE:** schema validators are only applied to content types you specify. Other content types are not blocked. Currently, API Gateway [supports](https://docs.aws.amazon.com/apigateway/latest/developerguide/models-mappings.html) JSON Schema draft-04.
+
 ### Schedule
 
 The following config will attach a schedule event and causes the stateMachine `crawl` to be called every 2 hours. The configuration allows you to attach multiple schedules to the same stateMachine. You can either use the `rate` or `cron` syntax. Take a look at the [AWS schedule syntax documentation](http://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html) for more details.