docs: Add deprecation plus docs adjustments

docs/deprecations.md

@@ -17,6 +17,14 @@ disabledDeprecations:
   - '*' # To disable all deprecation messages
 ```
 
+<a name="AWS_API_GATEWAY_SCHEMAS"><div>&nbsp;</div></a>
+
+## AWS API Gateway schemas
+
+Deprecation code: `AWS_API_GATEWAY_SCHEMAS`
+
+Starting with v3.0.0, `http.request.schema` property will be replaced by `http.request.schemas`. In addition to supporting functionalities such as model name definition and reuse of existing schemas, `http.request.schemas` also supports the same notation as `http.request.schema`, so you can safely migrate your existing configuration to the new property. For more details about the new configuration, please refer to the [API Gateway Event](/framework/docs/providers/aws/events/apigateway.md)
+
 <a name="AWS_EVENT_BRIDGE_CUSTOM_RESOURCE"><div>&nbsp;</div></a>
 
 ## AWS EventBridge lambda event triggers

docs/providers/aws/events/apigateway.md

@@ -805,11 +805,11 @@ functions:
           path: posts/create
           method: post
           request:
-            schema:
+            schemas:
               application/json: ${file(create_request.json)}
 ```
 
-API Gateway models can be customized by inline properties
+In addition, you can also customize created model with `name` and `description` properties.
 
 ```yml
 functions:
@@ -827,8 +827,9 @@ functions:
                 description: 'Validation model for Creating Posts'
 ```
 
-API Gateway models can be references by global models in the provider. The same structure exist
-for models defined in the provider as inline functions. Provider models default to `application/json`
+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.
 
 ```yml
 provider:

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

@@ -135,11 +135,11 @@ provider:
         burstLimit: 200
         rateLimit: 100
     request:
-      schemas:
+      schemas: # Optional request schema validation models that can be reused in `http` events. It is always defined for `application/json` content type
         global-model:
-          name: GlobalModel
-          schema: ${file(schema.json)}
-          description: "A global model that can be referenced in functions"
+          name: GlobalModel # Optional: Name of the API Gateway model
+          description: "A global model that can be referenced in functions" # Optional: Description of the API Gateway model
+          schema: ${file(schema.json)}  # Valid JSON Schema
   alb:
     targetGroupPrefix: xxxxxxxxxx # Optional prefix to prepend when generating names for target groups
     authorizers:
@@ -342,13 +342,11 @@ functions:
             template: # Optional custom request mapping templates that overwrite default templates
               application/json: '{ "httpMethod" : "$context.httpMethod" }'
             passThrough: NEVER # Optional define pass through behavior when content-type does not match any of the specified mapping templates
-            schemas:
+            schemas: # Optional request schema validation, mappped by content type
               application/json:
-                name: ModelName
-                description: "Some description"
-                schema: ${file(model_schema.json)}
-          schema:
-            application/json: ${file(model_schema.json)}
+                name: ModelName  # Optional: Name of the API Gateway model
+                description: "Some description" # Optional: Description of the API Gateway model
+                schema: ${file(model_schema.json)} # Schema for selected content type
       - httpApi: # HTTP API endpoint
           method: GET
           path: /some-get-path/{param}

lib/plugins/aws/package/compile/events/apiGateway/index.js

@@ -268,6 +268,18 @@ class AwsCompileApigEvents {
               'to "provider.apiGateway"'
           );
         }
+
+        if (
+          this.serverless.service.provider.name === 'aws' &&
+          Object.values(this.serverless.service.functions).some(({ events }) =>
+            events.some(({ http }) => _.get(http, 'request.schema'))
+          )
+        ) {
+          this.serverless._logDeprecation(
+            'AWS_API_GATEWAY_SCHEMAS',
+            'Starting with next major version, `http.request.schema` property will be replaced by `http.request.schemas`.'
+          );
+        }
       },
       'package:compileEvents': async () => {
         this.validated = this.validate();