Skip to content

Commit fe5479c

Browse files
mee-aasugmanue
mee-aa
and
sugmanue
authored
Add gatewayResponses trait and OpenAPI mapper (smithy-lang#3089)
* Add gatewayResponses trait and OpenAPI mapper API Gateway REST APIs support custom gateway responses that customize error responses for authentication failures, integration errors, and other API Gateway-generated errors. Add the `aws.apigateway#gatewayResponses` map trait that maps response type keys to gateway response structures containing statusCode, responseParameters, and responseTemplates. The OpenAPI mapper writes the trait value to the `x-amazon-apigateway-gateway-responses` extension. The mapper runs before the CORS gateway responses mapper so that customer-defined response parameters take precedence over CORS-generated headers. * Refactor GatewayResponsesTrait to use builder pattern Add GatewayResponse value class with builder following the same pattern as AuthorizersTrait and DefineConditionKeysTrait. Add DANGER validator for gatewayResponses and CORS conflicts. Fix RST header formatting in documentation. * Update smithy-aws-apigateway-openapi/src/main/java/software/amazon/smithy/aws/apigateway/openapi/AddGatewayResponses.java Co-authored-by: Manuel Sugawara <sugmanue@amazon.com> * Update smithy-aws-apigateway-traits/src/main/java/software/amazon/smithy/aws/apigateway/traits/GatewayResponsesTrait.java Co-authored-by: Manuel Sugawara <sugmanue@amazon.com> * Update smithy-aws-apigateway-traits/src/main/java/software/amazon/smithy/aws/apigateway/traits/GatewayResponsesTrait.java Co-authored-by: Manuel Sugawara <sugmanue@amazon.com> * Update smithy-aws-apigateway-traits/src/main/java/software/amazon/smithy/aws/apigateway/traits/GatewayResponsesTrait.java Co-authored-by: Manuel Sugawara <sugmanue@amazon.com> * Update smithy-aws-apigateway-traits/src/main/java/software/amazon/smithy/aws/apigateway/traits/GatewayResponsesTrait.java Co-authored-by: Manuel Sugawara <sugmanue@amazon.com> * Update smithy-aws-apigateway-traits/src/main/java/software/amazon/smithy/aws/apigateway/traits/GatewayResponsesTrait.java Co-authored-by: Manuel Sugawara <sugmanue@amazon.com> * Replace streams with loops and add bulk builder methods Replace stream-based serialization with plain loops in GatewayResponse.toNode() and GatewayResponsesTrait.createNode(). Add responses(), responseParameters(), and responseTemplates() bulk setter methods to the builders. * Update smithy-aws-apigateway-traits/src/main/java/software/amazon/smithy/aws/apigateway/traits/GatewayResponse.java * Update smithy-aws-apigateway-traits/src/main/java/software/amazon/smithy/aws/apigateway/traits/GatewayResponse.java * Update smithy-aws-apigateway-traits/src/main/java/software/amazon/smithy/aws/apigateway/traits/GatewayResponsesTrait.java * Update smithy-aws-apigateway-traits/src/main/java/software/amazon/smithy/aws/apigateway/traits/GatewayResponsesTrait.java * Update smithy-aws-apigateway-openapi/src/main/java/software/amazon/smithy/aws/apigateway/openapi/AddGatewayResponses.java * Update smithy-aws-apigateway-traits/src/main/java/software/amazon/smithy/aws/apigateway/traits/GatewayResponsesTrait.java * Update smithy-aws-apigateway-traits/src/main/java/software/amazon/smithy/aws/apigateway/traits/GatewayResponsesTrait.java --------- Co-authored-by: Manuel Sugawara <sugmanue@amazon.com>
1 parent bb2c97a commit fe5479c

18 files changed

Lines changed: 947 additions & 420 deletions

File tree

‎.changes/next-release/feature-a9137307ddc4298147690ffa212c94060b9710d7.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"type": "feature",
3+
"description": "Added `aws.apigateway#gatewayResponses` trait and OpenAPI mapper with DANGER validation for CORS conflicts",
4+
"pull_requests": [
5+
"[#3089](https://github.com/smithy-lang/smithy/pull/3089)"
6+
]
7+
}

‎docs/source-2.0/aws/amazon-apigateway.rst‎

Lines changed: 54 additions & 210 deletions
Original file line numberDiff line numberDiff line change
@@ -59,48 +59,6 @@ The following example sets the ``X-API-Key`` header as the API key source.
5959
customers.
6060

6161

62-
.. smithy-trait:: aws.apigateway#apiKeyRequired
63-
.. _aws.apigateway#apiKeyRequired-trait:
64-
65-
---------------------------------------
66-
``aws.apigateway#apiKeyRequired`` trait
67-
---------------------------------------
68-
69-
Summary
70-
Indicates that an operation requires an API key for API Gateway usage
71-
plan enforcement.
72-
Trait selector
73-
``operation``
74-
Value type
75-
Annotation trait (no value)
76-
See also
77-
- `Create and Use Usage Plans with API Keys`_ for more information on
78-
API key enforcement
79-
80-
The following example requires an API key on the ``ListItems`` operation
81-
but not on ``HealthCheck``:
82-
83-
.. code-block:: smithy
84-
85-
$version: "2"
86-
87-
namespace smithy.example
88-
89-
use aws.apigateway#apiKeyRequired
90-
91-
@apiKeyRequired
92-
@http(method: "GET", uri: "/items")
93-
operation ListItems {}
94-
95-
@http(method: "GET", uri: "/health")
96-
operation HealthCheck {}
97-
98-
.. note::
99-
100-
This trait should be considered internal-only and not exposed to your
101-
customers.
102-
103-
10462
.. smithy-trait:: aws.apigateway#authorizers
10563
.. _aws.apigateway#authorizers-trait:
10664

@@ -282,41 +240,6 @@ Value type
282240
customers.
283241

284242

285-
.. smithy-trait:: aws.apigateway#minimumCompressionSize
286-
.. _aws.apigateway#minimumCompressionSize-trait:
287-
288-
-----------------------------------------------
289-
``aws.apigateway#minimumCompressionSize`` trait
290-
-----------------------------------------------
291-
292-
Summary
293-
Defines the minimum payload size in bytes at which compression is applied
294-
on an API Gateway REST API.
295-
Trait selector
296-
``service``
297-
Value type
298-
``integer`` value between 0 and 10485760 (10MB).
299-
See also
300-
- `Payload compression for REST APIs`_ for more information
301-
- `x-amazon-apigateway-minimum-compression-size`_ for how this relates
302-
to OpenAPI
303-
304-
The following example sets the minimum compression size to 10240 bytes:
305-
306-
.. code-block:: smithy
307-
308-
$version: "2"
309-
310-
namespace smithy.example
311-
312-
use aws.apigateway#minimumCompressionSize
313-
314-
@minimumCompressionSize(10240)
315-
service Weather {
316-
version: "2018-03-17"
317-
}
318-
319-
320243
.. smithy-trait:: aws.apigateway#requestValidator
321244
.. _aws.apigateway#requestValidator-trait:
322245

@@ -485,25 +408,6 @@ following members:
485408
- Defines the method's responses and specifies desired parameter
486409
mappings or payload mappings from integration responses to method
487410
responses.
488-
* - tlsConfig
489-
- ``structure``
490-
- Specifies the TLS configuration for an integration. Supported only
491-
for HTTP and HTTP_PROXY integration types. Contains the following
492-
member:
493-
494-
- ``insecureSkipVerification`` (``boolean``): When set to ``true``,
495-
API Gateway skips verification that the certificate for an
496-
integration endpoint is issued by a supported certificate
497-
authority.
498-
* - responseTransferMode
499-
- ``string``
500-
- Specifies how the response payload is transferred between the
501-
integration and the caller. Valid values are ``BUFFERED`` and
502-
``STREAM``.
503-
* - integrationTarget
504-
- ``string``
505-
- The ARN of an ALB or NLB listener for private integrations using
506-
VPC Links V2.
507411

508412
The following example defines an integration that is applied to every
509413
operation within the service.
@@ -681,29 +585,27 @@ The following example defines an operation that uses a mock integration.
681585
customers.
682586

683587

684-
.. smithy-trait:: aws.apigateway#endpointConfiguration
685-
.. _aws.apigateway#endpointConfiguration-trait:
588+
.. smithy-trait:: aws.apigateway#gatewayResponses
589+
.. _aws.apigateway#gatewayResponses-trait:
686590

687-
---------------------------------------------------
688-
``aws.apigateway#endpointConfiguration`` trait
689-
---------------------------------------------------
591+
-----------------------------------------
592+
``aws.apigateway#gatewayResponses`` trait
593+
-----------------------------------------
690594

691595
Summary
692-
Defines the endpoint configuration for an API Gateway REST API,
693-
including the endpoint type, Virtual Private Cloud (VPC) `endpoint IDs`_,
694-
and whether the default ``execute-api`` endpoint is disabled.
596+
Defines custom gateway responses for an API Gateway REST API. Gateway
597+
responses customize error responses for authentication failures,
598+
integration errors, and other API Gateway-generated errors.
695599
Trait selector
696600
``service``
697601
Value type
698-
``structure``
602+
``map`` of response type ``string`` to ``GatewayResponse`` structure
699603
See also
700-
- `API endpoint types for REST APIs`_ for more information on
701-
endpoint types
702-
- `x-amazon-apigateway-endpoint-configuration`_ for the related
703-
OpenAPI extension
604+
- `x-amazon-apigateway-gateway-responses`_ for the related OpenAPI
605+
extension
606+
- `Gateway response types`_ for the list of valid response type keys
704607

705-
The ``aws.apigateway#endpointConfiguration`` trait is a structure that
706-
supports the following members:
608+
The ``GatewayResponse`` structure supports the following members:
707609

708610
.. list-table::
709611
:header-rows: 1
@@ -712,111 +614,58 @@ supports the following members:
712614
* - Property
713615
- Type
714616
- Description
715-
* - types
716-
- ``list`` of ``string`` **required**
717-
- The endpoint types for the API. Valid values are ``EDGE``,
718-
``REGIONAL``, and ``PRIVATE``.
719-
* - vpcEndpointIds
720-
- ``list`` of ``string``
721-
- A list of VPC endpoint IDs for ``PRIVATE`` endpoint type APIs.
722-
* - disableExecuteApiEndpoint
723-
- ``boolean``
724-
- Whether clients can invoke the API using the default
725-
``execute-api`` endpoint.
726-
727-
The following example configures a private API with a VPC endpoint and
728-
disables the default endpoint:
729-
730-
.. code-block:: smithy
731-
732-
$version: "2"
733-
734-
namespace smithy.example
735-
736-
use aws.apigateway#endpointConfiguration
737-
738-
@endpointConfiguration(
739-
types: ["PRIVATE"]
740-
vpcEndpointIds: ["vpce-0212a4ababd5b8c3e"]
741-
disableExecuteApiEndpoint: true
742-
)
743-
service Weather {
744-
version: "2018-03-17"
745-
}
746-
747-
.. note::
748-
749-
This trait should be considered internal-only and not exposed to your
750-
customers.
751-
752-
753-
.. smithy-trait:: aws.apigateway#resourcePolicy
754-
.. _aws.apigateway#resourcePolicy-trait:
755-
756-
---------------------------------------
757-
``aws.apigateway#resourcePolicy`` trait
758-
---------------------------------------
759-
760-
Summary
761-
Defines a resource policy for an API Gateway REST API. A resource
762-
policy is a JSON policy document attached to an API that controls
763-
whether a specified principal (typically an IAM role or group) can
764-
invoke the API.
765-
Trait selector
766-
``service``
767-
Value type
768-
``document``
769-
See also
770-
- `Resource policies for REST APIs`_ for more information
771-
- `x-amazon-apigateway-policy`_ for how this relates to OpenAPI
617+
* - statusCode
618+
- ``string``
619+
- The HTTP status code for the gateway response.
620+
* - responseParameters
621+
- ``map`` of ``string`` to ``string``
622+
- Response parameters for the gateway response. Keys use the format
623+
``gatewayresponse.header.<header-name>``.
624+
* - responseTemplates
625+
- ``map`` of ``string`` to ``string``
626+
- Response templates keyed by media type.
772627

773628
.. note::
774629

775-
Smithy does not validate the contents of the resource policy document.
776-
The policy is passed through to API Gateway, which validates it at
777-
import time.
630+
Response type keys (``DEFAULT_4XX``, ``DEFAULT_5XX``,
631+
``INVALID_API_KEY``, etc.) are validated by API Gateway at import
632+
time, not by Smithy. When both ``@gatewayResponses`` and ``@cors``
633+
are applied to a service, the gateway responses take precedence.
634+
The CORS mapper merges its headers into gateway responses without
635+
overwriting customer-defined response parameters.
778636

779-
The following example defines a resource policy that allows any principal to
780-
invoke the API except for requests from the specified source IP address block:
637+
The following example defines custom gateway responses for 4xx and 5xx
638+
errors:
781639

782640
.. code-block:: smithy
783641
784642
$version: "2"
785643
786644
namespace smithy.example
787645
788-
use aws.apigateway#resourcePolicy
646+
use aws.apigateway#gatewayResponses
789647
790-
@resourcePolicy({
791-
"Version": "2012-10-17"
792-
"Statement": [
793-
{
794-
"Effect": "Allow"
795-
"Principal": "*"
796-
"Action": "execute-api:Invoke"
797-
"Resource": ["execute-api:/*"]
648+
@gatewayResponses(
649+
"DEFAULT_4XX": {
650+
statusCode: "400"
651+
responseParameters: {
652+
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
798653
}
799-
{
800-
"Effect": "Deny"
801-
"Principal": "*"
802-
"Action": "execute-api:Invoke"
803-
"Resource": ["execute-api:/*"]
804-
"Condition": {
805-
"IpAddress": {
806-
"aws:SourceIp": "192.0.2.0/24"
807-
}
808-
}
654+
responseTemplates: {
655+
"application/json": "{\"message\": \"bad request\"}"
809656
}
810-
]
811-
})
657+
}
658+
"DEFAULT_5XX": {
659+
statusCode: "500"
660+
responseTemplates: {
661+
"application/json": "{\"message\": \"Internal server error\"}"
662+
}
663+
}
664+
)
812665
service Weather {
813666
version: "2018-03-17"
814667
}
815668
816-
.. note::
817-
818-
This trait should be considered internal-only and not exposed to your
819-
customers.
820669
821670
-----------------------
822671
Shared trait data types
@@ -1110,25 +959,20 @@ integration response to two ``header`` parameters of the method response.
1110959
1111960
1112961
.. _Enable Request Validation in API Gateway: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-request-validation.html
1113-
.. _x-amazon-apigateway-request-validator: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-request-validator.html
962+
.. _x-amazon-apigateway-request-validator: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-request-validators.requestValidator.html
1114963
.. _x-amazon-apigateway-request-validators: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-request-validators.html
1115964
.. _Granting Permissions Using a Resource Policy: https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy
1116-
.. _Integration.passthroughBehavior: https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#passthroughBehavior
1117-
.. _VpcLink: https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html
965+
.. _Integration.passthroughBehavior: https://docs.aws.amazon.com/apigateway/api-reference/resource/integration/#passthroughBehavior
966+
.. _VpcLink: https://docs.aws.amazon.com/apigateway/api-reference/resource/vpc-link/
1118967
.. _x-amazon-apigateway-integration: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration.html
1119-
.. _API Gateway integration: https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html
968+
.. _API Gateway integration: https://docs.aws.amazon.com/apigateway/api-reference/resource/integration/
1120969
.. _Lambda authorizers: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-authorizer.html
1121970
.. _x-amazon-apigateway-authtype: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-authtype.html
1122971
.. _Create and Use Usage Plans with API Keys: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html
1123972
.. _Choose an API Key Source: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-key-source.html
1124973
.. _x-amazon-apigateway-api-key-source: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-api-key-source.html
1125-
.. _IntegrationResponse: https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html
974+
.. _IntegrationResponse: https://docs.aws.amazon.com/apigateway/api-reference/resource/integration-response/
1126975
.. _mapping templates: https://docs.aws.amazon.com/apigateway/latest/developerguide/models-mappings.html#models-mappings-mappings
1127976
.. _Lambda Authorizers Payload Format: https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-lambda-authorizer.html#http-api-lambda-authorizer.payload-format
1128-
.. _x-amazon-apigateway-endpoint-configuration: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html
1129-
.. _API endpoint types for REST APIs: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-endpoint-types.html
1130-
.. _endpoint IDs: https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html#concepts-vpc-endpoints
1131-
.. _Payload compression for REST APIs: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-gzip-compression-decompression.html
1132-
.. _x-amazon-apigateway-minimum-compression-size: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-openapi-minimum-compression-size.html
1133-
.. _Resource policies for REST APIs: https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies.html
1134-
.. _x-amazon-apigateway-policy: https://docs.aws.amazon.com/apigateway/latest/developerguide/openapi-extensions-policy.html
977+
.. _x-amazon-apigateway-gateway-responses: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-gateway-responses.html
978+
.. _Gateway response types: https://docs.aws.amazon.com/apigateway/latest/developerguide/supported-gateway-response-types.html

0 commit comments

Comments
 (0)