Solving MISSING_PATH_PARAMETER_DEFINITION when exporting from AWS API Gateway in Swagger Format

A bug in AWS API Gateway after enabling CORS and exporting resources with path parameters

A few days ago I stumbled upon what it seems to be a bug in AWS API Gateway, triggered when exporting an API in Swagger format.

As you may know already, Swagger makes it really easy to share your REST API specification and also generate clients for it, so it was really important that this worked perfectly.

The bug in question is that when exporting your Amazon AWS API Gateway specification to the Swagger format an invalid format can be generated if one or more of your Resources use path parameters and you have enabled CORS for them.

The invalid format can also be noticed in the Online Swagger Editor, that will show errors like this one:

Swagger Error

Path parameter is declared but is not defined: id
Jump to line xxx
message: "Path parameter is declared but is not defined: id"
path: Array [3]
level: xxx
type: "Swagger Error"
description: "Path parameter is declared but is not defined: id"
lineNumber: xxx

The bug seems to manifest itself when enabling CORS on an API Gateway Resource (that automatically generates the OPTIONS method) that uses path parameters.

The Resource in question has to use path parameters, for example: /users/{id}. It seems that when you enable CORS on resources like this one, the exportation will not take into account the arguments needed for the OPTIONS method.

Fixing the Path Parameter error when exporting Resources with CORS enabled from API Gateway in Swagger Format

This fix is actually a work around, the definite fix is still in the works by the Amazon AWS API Gateway team.

The solution seems to be to manually create the OPTIONS method with a mock integration and only then, enable CORS for the resource.

If you have already enabled CORS, the solution is to delete the OPTIONS method in all the resources that use path parameters and manually recreate them, enabling CORS afterwards.