デフォルトのエンドポイントの有効無効をAWS CFnテンプレートとOpenAPIで指定する

AWS CloudFormation と OpenAPI を使用して Amazon API Gateway を構築する時、「デフォルトのエンドポイント」を無効にする方法がわかりづらかったので、ノウハウを残します。

AWS SAM の AWS::Serverless::API リソースには、デフォルトのエンドポイントの有効と無効を切り替える DisableExecuteApiEndpoint プロパティがあります。

しかし、AWS CloudFormation テンプレートで OpenAPI を DefinitionUri 使用して設定している場合（調査中）、DisableExecuteApiEndpoint プロパティが効きません。

従って、AWS の OpenAPI 拡張を使用し、AWS CloudFormation テンプレートではなく、OpenAPI 内に設定を定義する必要があります。デフォルトのエンドポイントの有効と無効を切り替える AWS の OpenAPI 拡張は、x-amazon-apigateway-endpoint-configuration オブジェクトです。

公式ドキュメントに記載されている通り、x-amazon-apigateway-endpoint-configuration オブジェクトは Swagger 2.0 の場合は「最上位ベンダー拡張」、OpenAPI 3.0 の場合は「server オブジェクトのベンダー拡張の下」に設定します。

ここでわかりづらかったのが、「server オブジェクトのベンダー拡張の下」という記述です。具体的にどこなのか。OpenAPI （Swagger）の公式ドキュメントの「Server Object」を読むと This object MAY be extended with Specification Extensions と記載されています。

結論は、以下の通り、servers フィールドに列挙する server オブジェクトの直下です。

openapi.yaml

openapi: 3.0.3
info:
  title: sample-api
  description: Sample API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: Development server.
    x-amazon-apigateway-endpoint-configuration:
      disableExecuteApiEndpoint: true
  - url: https://api.example.com/v1
    description: Production server.

尚、AWS CloudFormation と OpenAPI を使用して Amazon API Gateway を構築する時に複数のサーバーを列挙した場合、一番先頭に記述した設定のみが使用されます。複数のサーバーを列挙する場合、一番先頭の server オブジェクトにのみ設定を記述すれば、有効になります。