AWS API Gateway部署Swagger配置报Invalid mapping expression参数错误求助

First off, I totally get your frustration—official docs can be surprisingly vague when it comes to edge cases or version-specific nuances, so copying their example and still hitting an error is really annoying. Let’s walk through the most common fixes for this issue:

• Check Swagger/OpenAPI version compatibility with API Gateway
  AWS API Gateway has strict requirements for OpenAPI 2.0 (Swagger) vs. OpenAPI 3.0. A lot of older official examples are written for OpenAPI 2.0, and if you’re using 3.0, some mapping expression syntax or integration fields will break. For example:

  • In OpenAPI 3.0, integration request parameters use requestParameters under x-amazon-apigateway-integration but the syntax for referencing method parameters differs slightly from 2.0.
  • Double-check that your Swagger version (swagger: "2.0" vs. openapi: 3.0.0) matches the version the official example was built for.

• Validate your mapping expression syntax and parameter references
  The error almost always means API Gateway can’t locate the parameter you’re referencing in your mapping. Common mistakes here:

  • Typos in parameter names: If you’re referencing method.request.path.user-id but your API defines the path parameter as userId, that’ll fail.
  • Missing $ prefix in expressions: Make sure your expressions start with $, like $input.path('$.body.email') instead of input.path('$.body.email').
  • Referencing an undefined parameter: If your example uses $input.params('queryParam') but you haven’t defined that query parameter in your Swagger’s parameters section, API Gateway will throw this error.

• Audit your x-amazon-apigateway-integration config
  This is where most mapping issues hide. For example:

  • If you’re using requestParameters to map method parameters to integration parameters (like "integration.request.path.id": "method.request.path.id"), ensure method.request.path.id is actually defined in your API’s paths section.
  • For request/response templates, confirm the variables you’re using (like $context.requestId) are valid API Gateway variables—some older examples might reference deprecated values.

• Simplify to isolate the problem
  Strip down your Swagger config to the absolute minimum: remove all mappings, templates, and extra parameters, then deploy. If that works, add back one component at a time (first the base integration, then a single mapping expression) and deploy after each change. This will tell you exactly which line or section is causing the error.

• Use the AWS Console to get detailed error context
  When you deploy from the CLI or Swagger and get the generic error, head to the AWS API Gateway Console. Go to your API, check the "Deployments" tab, and look for the failed deployment. Click into it—AWS will often show a specific breakdown, like "Invalid parameter reference: method.request.queryParam.name does not exist", which points you directly to the problem.

I’ve run into this exact issue before with official examples—sometimes they assume you’re using a specific API type (REST vs. HTTP API) or have certain parameters pre-defined that aren’t explicitly stated in the example. Taking it step by step to isolate the issue usually works.

内容的提问来源于stack exchange，提问作者RomaValcer