Avoiding a stage called "Stage"

[copumpkin]

I've noticed that my API Gateway deployments from SAM generate a stage called "Stage". It looks like that comes from this snippet of code:

https://github.com/awslabs/serverless-application-model/blob/2de2304916aadad3f5d6da5b29dce9f9eae081c3/samtranslator/model/api/api_generator.py#L172-L173

And oddly enough, self.remove_extra_stage is defined to match open_api_version, but only seems to be treated for its truthiness. So basically, it seems like I specify OpenApiVersion in my Serverless::Api, the mysterious "Stage" stage doesn't get generated.

Is that deliberate? The behavior seems surprising to me and it's unclear to me why specifying an openapi version would govern whether that stage gets created with a seemingly useless name. I see that line came from this PR but it doesn't explain why that behavior is desirable.

Could this behavior be clarified in documentation or exposed more directly to users with some sort of boolean to turn it off? I don't really care to specify my openapi version, but I don't want the extra stage, and it's unclear if I can do that today.

[chrisoverzero]

For reasons of backwards compatibility, the extra stage must continue to be created by default. However, the SAM team determined – once the new version of Open API became available – that explicitly specifying a version (even it was ‘2.0’) was a strong enough signal that the compatibility concerns had been considered.

Backwards compatibility rules all, especially in this case. This behavior is documented in the SAM specification next to the definition of the OpenApiVersion property on AWS::Serverless::API.

[…] it’s unclear if I can do that today.

You cannot. In my opinion, it would be best to specify an Open API document version.

[keetonian]

@copumpkin like @chrisoverzero said, you can remove the stage Stage by specifying anything in the OpenApiVersion property, and this was to maintain backwards compatibility.

We definitely can make this more clear in the documentation. I'll add a label to this issue to update our documentation.

[GiltosMx]

Hi there. I ran into this issue as well, and was not sure if the stage called Stage had been created because of an error in my SAM template.

I took the liberty to improve this myself. I created an issue and Pull Request in the aws-sam-developer-guide repository:

• Issue #142
• Pull Request

If those changes get applied, maybe this issue can be closed.
Cheers!

[hoffa]

Relevant: #2077

[hoffa]

We've clarified the phrasing: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-api.html#sam-api-openapiversion