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();

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

@@ -38,11 +38,7 @@ module.exports = {
           // New resources need to be created
           if (
             _.isObject(schemaConfig) ||
-            !(
-              apiGatewayConfig.request &&
-              apiGatewayConfig.request.schemas &&
-              apiGatewayConfig.request.schemas[schemaConfig]
-            )
+            !_.get(apiGatewayConfig, `request.schemas.${schemaConfig}`)
           ) {
             modelLogicalId = this.provider.naming.getEndpointModelLogicalId(
               resourceName,
@@ -63,6 +59,8 @@ module.exports = {
                     RestApiId: this.provider.getApiGatewayRestApiId(),
                     ContentType: contentType,
                     Schema: definition,
+                    Name: modelName,
+                    Description: description,
                   },
                 },
 
@@ -72,30 +70,12 @@ module.exports = {
                     RestApiId: this.provider.getApiGatewayRestApiId(),
                     ValidateRequestBody: true,
                     ValidateRequestParameters: true,
+                    Name: validatorName,
                   },
                 },
               }
             );
-
-            if (modelName) {
-              this.serverless.service.provider.compiledCloudFormationTemplate.Resources[
-                modelLogicalId
-              ].Properties.Name = modelName;
-              this.serverless.service.provider.compiledCloudFormationTemplate.Resources[
-                validatorLogicalId
-              ].Properties.Name = validatorName;
-            }
-
-            if (description) {
-              this.serverless.service.provider.compiledCloudFormationTemplate.Resources[
-                modelLogicalId
-              ].Properties.Description = description;
-            }
-          } else if (
-            apiGatewayConfig.request &&
-            apiGatewayConfig.request.schemas &&
-            apiGatewayConfig.request.schemas[schemaConfig]
-          ) {
+          } else if (_.get(apiGatewayConfig, `request.schemas.${schemaConfig}`)) {
             const models = this.createProviderModel(
               schemaConfig,
               apiGatewayConfig.request.schemas[schemaConfig]

test/unit/lib/plugins/aws/package/compile/events/apiGateway/lib/requestValidator.test.js

@@ -142,6 +142,8 @@ describe('#compileRequestValidators()', () => {
           RestApiId: {
             Ref: 'ApiGatewayRestApi',
           },
+          Description: undefined,
+          Name: undefined,
           Schema: {
             $schema: 'http://json-schema.org/draft-04/schema#',
             definitions: {},
@@ -254,6 +256,8 @@ describe('#compileRequestValidators()', () => {
           RestApiId: {
             Ref: 'ApiGatewayRestApi',
           },
+          Description: undefined,
+          Name: undefined,
           Schema: {
             $schema: 'http://json-schema.org/draft-04/schema#',
             definitions: {},
@@ -275,6 +279,8 @@ describe('#compileRequestValidators()', () => {
         Type: 'AWS::ApiGateway::Model',
         Properties: {
           ContentType: 'text/plain',
+          Description: undefined,
+          Name: undefined,
           RestApiId: {
             Ref: 'ApiGatewayRestApi',
           },