Add ipAddressType and mapper for endpointConfiguration

API Gateway REST APIs support an ipAddressType property on the
endpoint configuration that controls whether an API accepts IPv4,
IPv6, or both. The @endpointConfiguration trait did not model this
property, and the trait had no OpenAPI mapper, so VPC endpoint IDs
and the default-endpoint disable flag had to be set via jsonAdd
workarounds.

Add an ipAddressType string member to the trait with supported
values `ipv4` and `dualstack`. Add the AddEndpointConfiguration
OpenAPI mapper that writes vpcEndpointIds and disableExecuteApiEndpoint
to the x-amazon-apigateway-endpoint-configuration extension. The
types and ipAddressType members are omitted because they are
configured outside of the OpenAPI document at API import time.
Add a CloudFormation substitution path for vpcEndpointIds.

Author: mee-aa

.changes/next-release/feature-endpoint-configuration-ip-address-type.json

@@ -0,0 +1,7 @@
+{
+  "type": "feature",
+  "description": "Added `ipAddressType` field to the `aws.apigateway#endpointConfiguration` trait and added an OpenAPI mapper that writes `vpcEndpointIds` and `disableExecuteApiEndpoint` to the `x-amazon-apigateway-endpoint-configuration` extension.",
+  "pull_requests": [
+    "[#3110](https://github.com/smithy-lang/smithy/pull/3110)"
+  ]
+}

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

@@ -466,6 +466,8 @@ Value type
 See also
     - `API endpoint types for REST APIs`_ for more information on
       endpoint types
+    - `IP address types for REST APIs`_ for more information on the
+      ``ipAddressType`` property
     - `x-amazon-apigateway-endpoint-configuration`_ for the related
       OpenAPI extension
 
@@ -490,6 +492,11 @@ supports the following members:
       - ``boolean``
       - Whether clients can invoke the API using the default
         ``execute-api`` endpoint.
+    * - ipAddressType
+      - ``string`` enum (``ipv4`` or ``dualstack``)
+      - The IP address type that can invoke the API. For the ``PRIVATE``
+        endpoint type, only ``dualstack`` is supported. See
+        `IP address types for REST APIs`_ for details.
 
 The following example configures a private API with a VPC endpoint and
 disables the default endpoint:
@@ -506,6 +513,7 @@ disables the default endpoint:
         types: ["PRIVATE"]
         vpcEndpointIds: ["vpce-0212a4ababd5b8c3e"]
         disableExecuteApiEndpoint: true
+        ipAddressType: "dualstack"
     )
     service Weather {
       version: "2018-03-17"
@@ -1267,4 +1275,5 @@ integration response to two ``header`` parameters of the method response.
 .. _x-amazon-apigateway-policy: https://docs.aws.amazon.com/apigateway/latest/developerguide/openapi-extensions-policy.html
 .. _x-amazon-apigateway-endpoint-configuration: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html
 .. _API endpoint types for REST APIs: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-endpoint-types.html
+.. _IP address types for REST APIs: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-ip-address-type.html
 .. _endpoint IDs: https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html#concepts-vpc-endpoints

docs/source-2.0/guides/model-translations/converting-to-openapi.rst

@@ -2122,6 +2122,7 @@ uses the ``Fn::Sub`` variable syntax (``*`` means any value):
 - ``paths/*/*/x-amazon-apigateway-integration/connectionId``
 - ``paths/*/*/x-amazon-apigateway-integration/credentials``
 - ``paths/*/*/x-amazon-apigateway-integration/uri``
+- ``x-amazon-apigateway-endpoint-configuration/vpcEndpointIds/*``
 
 .. note::
 
@@ -2359,6 +2360,58 @@ is converted to the following OpenAPI model:
     }
 
 
+.. _apigateway-endpoint-configuration:
+
+Endpoint configuration
+======================
+
+The endpoint configuration for an API Gateway REST API can be set using the
+:ref:`aws.apigateway#endpointConfiguration-trait`. Smithy writes the
+``vpcEndpointIds`` and ``disableExecuteApiEndpoint`` values to the
+`x-amazon-apigateway-endpoint-configuration`_ extension in the generated
+OpenAPI document. The ``types`` and ``ipAddressType`` members are not part
+of this extension and are configured outside of the OpenAPI document at
+API import time.
+
+The following Smithy model configures a private API with VPC endpoints and
+disables the default ``execute-api`` endpoint:
+
+.. code-block:: smithy
+
+    $version: "2"
+    namespace smithy.example
+
+    use aws.apigateway#endpointConfiguration
+    use aws.protocols#restJson1
+
+    @restJson1
+    @endpointConfiguration(
+        types: ["PRIVATE"]
+        vpcEndpointIds: ["vpce-0212a4ababd5b8c3e"]
+        disableExecuteApiEndpoint: true
+        ipAddressType: "dualstack"
+    )
+    service Example {
+      version: "2019-06-17"
+    }
+
+is converted to the following OpenAPI model:
+
+.. code-block:: json
+
+    {
+        "openapi": "3.0.2",
+        "info": {
+            "title": "Example",
+            "version": "2019-06-17"
+        },
+        "x-amazon-apigateway-endpoint-configuration": {
+            "vpcEndpointIds": ["vpce-0212a4ababd5b8c3e"],
+            "disableExecuteApiEndpoint": true
+        }
+    }
+
+
 .. _other-traits:
 
 Other traits that influence API Gateway
@@ -2465,3 +2518,4 @@ The conversion process is highly extensible through
 .. _x-amazon-apigateway-gateway-responses: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-gateway-responses.html
 .. _x-amazon-apigateway-security-policy: https://docs.aws.amazon.com/apigateway/latest/developerguide/openapi-extensions-security-policy.html
 .. _x-amazon-apigateway-endpoint-access-mode: https://docs.aws.amazon.com/apigateway/latest/developerguide/openapi-extensions-endpoint-access-mode.html
+.. _x-amazon-apigateway-endpoint-configuration: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html

smithy-aws-apigateway-openapi/src/main/java/software/amazon/smithy/aws/apigateway/openapi/AddEndpointConfiguration.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package software.amazon.smithy.aws.apigateway.openapi;
+
+import java.util.List;
+import java.util.logging.Logger;
+import software.amazon.smithy.aws.apigateway.traits.EndpointConfigurationTrait;
+import software.amazon.smithy.model.node.ArrayNode;
+import software.amazon.smithy.model.node.Node;
+import software.amazon.smithy.model.node.ObjectNode;
+import software.amazon.smithy.model.traits.Trait;
+import software.amazon.smithy.openapi.fromsmithy.Context;
+import software.amazon.smithy.openapi.model.OpenApi;
+import software.amazon.smithy.utils.ListUtils;
+
+/**
+ * Adds the API Gateway {@code x-amazon-apigateway-endpoint-configuration}
+ * extension to the OpenAPI model when the {@link EndpointConfigurationTrait}
+ * is applied to a service.
+ *
+ * <p>The {@code types} member is not written to the extension because it is
+ * not a supported property of {@code x-amazon-apigateway-endpoint-configuration};
+ * endpoint types are configured outside of the OpenAPI extension at API import
+ * time.
+ *
+ * <p>The {@code ipAddressType} member is also omitted from the extension
+ * because it is not a supported property; it is configured outside of the
+ * OpenAPI extension at API import time.
+ *
+ * @see <a href="https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html">x-amazon-apigateway-endpoint-configuration</a>
+ */
+final class AddEndpointConfiguration implements ApiGatewayMapper {
+
+    private static final String EXTENSION_NAME = "x-amazon-apigateway-endpoint-configuration";
+    private static final String VPC_ENDPOINT_IDS = "vpcEndpointIds";
+    private static final String DISABLE_EXECUTE_API_ENDPOINT = "disableExecuteApiEndpoint";
+    private static final Logger LOGGER = Logger.getLogger(AddEndpointConfiguration.class.getName());
+
+    @Override
+    public List<ApiGatewayConfig.ApiType> getApiTypes() {
+        return ListUtils.of(ApiGatewayConfig.ApiType.REST);
+    }
+
+    @Override
+    public OpenApi after(Context<? extends Trait> context, OpenApi openApi) {
+        return context.getService()
+                .getTrait(EndpointConfigurationTrait.class)
+                .map(trait -> addExtension(context, openApi, trait))
+                .orElse(openApi);
+    }
+
+    private OpenApi addExtension(
+            Context<? extends Trait> context,
+            OpenApi openApi,
+            EndpointConfigurationTrait trait
+    ) {
+        ObjectNode.Builder node = Node.objectNodeBuilder();
+
+        trait.getVpcEndpointIds()
+                .ifPresent(ids -> node.withMember(
+                        VPC_ENDPOINT_IDS,
+                        ids.stream().map(Node::from).collect(ArrayNode.collect())));
+
+        trait.getDisableExecuteApiEndpoint()
+                .ifPresent(disabled -> node.withMember(
+                        DISABLE_EXECUTE_API_ENDPOINT,
+                        Node.from(disabled)));
+
+        ObjectNode extension = node.build();
+        if (extension.isEmpty()) {
+            return openApi;
+        }
+
+        LOGGER.fine(() -> String.format(
+                "Adding %s to %s",
+                EXTENSION_NAME,
+                context.getService().getId()));
+
+        return openApi.toBuilder().putExtension(EXTENSION_NAME, extension).build();
+    }
+}

smithy-aws-apigateway-openapi/src/main/java/software/amazon/smithy/aws/apigateway/openapi/ApiGatewayExtension.java

@@ -23,6 +23,7 @@ public List<OpenApiMapper> getOpenApiMappers() {
                 ApiGatewayMapper.wrap(new AddAuthorizers()),
                 ApiGatewayMapper.wrap(new AddBinaryTypes()),
                 ApiGatewayMapper.wrap(new AddCognitoUserPoolsScopes()),
+                ApiGatewayMapper.wrap(new AddEndpointConfiguration()),
                 ApiGatewayMapper.wrap(new AddIntegrations()),
                 ApiGatewayMapper.wrap(new AddMinimumCompressionSize()),
 

smithy-aws-apigateway-openapi/src/main/java/software/amazon/smithy/aws/apigateway/openapi/CloudFormationSubstitution.java

@@ -51,7 +51,8 @@ final class CloudFormationSubstitution implements ApiGatewayMapper {
             "paths/*/*/x-amazon-apigateway-integration/connectionId",
             "paths/*/*/x-amazon-apigateway-integration/credentials",
             "paths/*/*/x-amazon-apigateway-integration/uri",
-            "paths/*/*/x-amazon-apigateway-integration/integrationTarget");
+            "paths/*/*/x-amazon-apigateway-integration/integrationTarget",
+            "x-amazon-apigateway-endpoint-configuration/vpcEndpointIds/*");
 
     @Override
     public List<ApiGatewayConfig.ApiType> getApiTypes() {

smithy-aws-apigateway-openapi/src/test/java/software/amazon/smithy/aws/apigateway/openapi/AddEndpointConfigurationTest.java

@@ -0,0 +1,94 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package software.amazon.smithy.aws.apigateway.openapi;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.contains;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.is;
+
+import java.util.stream.Collectors;
+import org.junit.jupiter.api.Test;
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.node.ObjectNode;
+import software.amazon.smithy.model.node.StringNode;
+import software.amazon.smithy.model.shapes.ShapeId;
+import software.amazon.smithy.openapi.OpenApiConfig;
+import software.amazon.smithy.openapi.fromsmithy.OpenApiConverter;
+import software.amazon.smithy.openapi.model.OpenApi;
+
+public class AddEndpointConfigurationTest {
+    private static final String EXTENSION_NAME = "x-amazon-apigateway-endpoint-configuration";
+
+    @Test
+    public void addsExtensionWithVpcEndpointIdsAndDisableFlag() {
+        OpenApi result = convert("endpoint-configuration.smithy");
+
+        assertThat(result.getExtension(EXTENSION_NAME).isPresent(), is(true));
+        ObjectNode extension = result.getExtension(EXTENSION_NAME).get().expectObjectNode();
+
+        assertThat(extension.expectArrayMember("vpcEndpointIds")
+                .getElements()
+                .stream()
+                .map(node -> ((StringNode) node).getValue())
+                .collect(Collectors.toList()),
+                contains("vpce-0212a4ababd5b8c3e", "vpce-01d622316a7df47f9"));
+        assertThat(extension.expectBooleanMember("disableExecuteApiEndpoint").getValue(),
+                equalTo(true));
+
+        // types and ipAddressType are not part of the extension.
+        assertThat(extension.getMember("types").isPresent(), is(false));
+        assertThat(extension.getMember("ipAddressType").isPresent(), is(false));
+    }
+
+    @Test
+    public void omitsExtensionWhenOnlyTypesIsSet() {
+        OpenApi result = convert("endpoint-configuration-minimal.smithy");
+
+        // Only types is set on the trait, and types is not part of the
+        // extension. The mapper must not emit an empty extension.
+        assertThat(result.getExtension(EXTENSION_NAME).isPresent(), is(false));
+    }
+
+    @Test
+    public void wrapsVpcEndpointIdCloudFormationVariablesInFnSub() {
+        // The CFN substitution runs in updateNode, so convert to node to
+        // pick up Fn::Sub wrapping.
+        Model assembled = Model.assembler()
+                .discoverModels(getClass().getClassLoader())
+                .addImport(getClass().getResource("endpoint-configuration-cfn.smithy"))
+                .assemble()
+                .unwrap();
+        OpenApiConfig config = new OpenApiConfig();
+        config.setService(ShapeId.from("smithy.example#Service"));
+        ObjectNode result = OpenApiConverter.create()
+                .config(config)
+                .classLoader(getClass().getClassLoader())
+                .convertToNode(assembled);
+
+        ObjectNode extension = result.expectObjectMember(EXTENSION_NAME);
+        ObjectNode firstId = extension.expectArrayMember("vpcEndpointIds")
+                .get(0)
+                .get()
+                .expectObjectNode();
+
+        assertThat(firstId.expectStringMember("Fn::Sub").getValue(),
+                equalTo("${MyVpcEndpointId}"));
+    }
+
+    private OpenApi convert(String model) {
+        Model assembled = Model.assembler()
+                .discoverModels(getClass().getClassLoader())
+                .addImport(getClass().getResource(model))
+                .assemble()
+                .unwrap();
+        OpenApiConfig config = new OpenApiConfig();
+        config.setService(ShapeId.from("smithy.example#Service"));
+        return OpenApiConverter.create()
+                .config(config)
+                .classLoader(getClass().getClassLoader())
+                .convert(assembled);
+    }
+}

smithy-aws-apigateway-openapi/src/test/resources/software/amazon/smithy/aws/apigateway/openapi/endpoint-configuration-cfn.smithy

@@ -0,0 +1,20 @@
+$version: "2.0"
+
+namespace smithy.example
+
+use aws.apigateway#endpointConfiguration
+use aws.protocols#restJson1
+
+@restJson1
+@endpointConfiguration(
+    types: ["PRIVATE"]
+    vpcEndpointIds: ["${MyVpcEndpointId}"]
+    disableExecuteApiEndpoint: true
+)
+service Service {
+    version: "2006-03-01"
+    operations: [Operation]
+}
+
+@http(uri: "/", method: "GET")
+operation Operation {}

smithy-aws-apigateway-openapi/src/test/resources/software/amazon/smithy/aws/apigateway/openapi/endpoint-configuration-minimal.smithy

@@ -0,0 +1,19 @@
+$version: "2.0"
+
+namespace smithy.example
+
+use aws.apigateway#endpointConfiguration
+use aws.protocols#restJson1
+
+/// Only required `types` is set. No extension should be emitted because
+/// `types` and `ipAddressType` are not written to
+/// `x-amazon-apigateway-endpoint-configuration`.
+@restJson1
+@endpointConfiguration(types: ["REGIONAL"])
+service Service {
+    version: "2006-03-01"
+    operations: [Operation]
+}
+
+@http(uri: "/", method: "GET")
+operation Operation {}

smithy-aws-apigateway-openapi/src/test/resources/software/amazon/smithy/aws/apigateway/openapi/endpoint-configuration.smithy

@@ -0,0 +1,21 @@
+$version: "2.0"
+
+namespace smithy.example
+
+use aws.apigateway#endpointConfiguration
+use aws.protocols#restJson1
+
+@restJson1
+@endpointConfiguration(
+    types: ["PRIVATE"]
+    vpcEndpointIds: ["vpce-0212a4ababd5b8c3e", "vpce-01d622316a7df47f9"]
+    disableExecuteApiEndpoint: true
+    ipAddressType: "dualstack"
+)
+service Service {
+    version: "2006-03-01"
+    operations: [Operation]
+}
+
+@http(uri: "/", method: "GET")
+operation Operation {}