AWS SAM（AWS::Serverless::Api）で意図しない「Stage」ステージが作られる件の対処

1. はじめに

AWS SAM（AWS::Serverless::Api）で REST API をデプロイした際、意図したステージとは別に、Stage というステージが追加で作成されてしまうことがあります。

本記事では、この 不要な Stage ステージを作成させない回避策を、最小限の設定を紹介します。

2. 事象

• SAM テンプレートで StageName: V1 を指定している
• しかし、API Gateway のステージ一覧に V1 と Stage の2つが見える

3. 回避策：OpenApiVersion を明示する

AWS::Serverless::Api の OpenApiVersion に有効な値を設定すると、Stage ステージが作成されなくなります。

• 2.0（Swagger）
• 3.0.1 など（OpenAPI 3.0 系）

3-1. 書き方①：Globalsで指定する

AWS::Serverless::Api を明示的に書かず、Function の Events: Type: Api から暗黙的に API を生成している構成では、Globals 側で指定しておくと適用漏れを防ぎやすいです。

AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31

Globals:
  Api:
    OpenApiVersion: 3.0.1

Resources:
  HelloFunction:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: python3.12
      Handler: app.lambda_handler
      CodeUri: src/
      Events:
        Hello:
          Type: Api
          Properties:
            Path: /hello
            Method: get

3-2. 書き方②：AWS::Serverless::Apiに直接指定する

API リソースを明示している場合は、該当リソースのPropertiesに追加します。

Resources:
  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      OpenApiVersion: 3.0.1

  HelloFunction:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: python3.12
      Handler: app.lambda_handler
      CodeUri: src/
      Events:
        Hello:
          Type: Api
          Properties:
            RestApiId: !Ref MyApi
            Path: /hello
            Method: get

4. 既に「Stage」ステージが作成されてしまっている場合

OpenApiVersionを追加した後でも、過去に作成済みのStageが自動で消えるわけではありません。

運用上は以下の流れになります。

1. 既存の不要なStageは、必要に応じてコンソール等で削除
2. テンプレートにOpenApiVersionを追加してデプロイ

5. まとめ

• SAM の REST API で不要なStageステージが増える場合は、まずOpenApiVersionの未指定を疑うこと
• OpenApiVersionを明示すると、Stageステージの作成を回避できる