AWS SAM+NodeJS配置Swagger遇版本错误，求解决及本地测试方案

一、解决「OpenAPI版本无效」错误 #

错误提示Error: An invalid OpenApi version was detected: '', must be one of 2.x or 3.x，本质是SAM未能正确读取到swagger.yaml中的OpenAPI版本信息，以下是针对性解决方案：

1. 验证S3文件路径与内容 #

• 确认S3BucketName参数对应的S3桶存在，且swagger.yaml文件确实存放在桶的指定路径下
• 用AWS CLI命令校验文件可用性：

  aws s3 cp s3://<你的桶名>/swagger.yaml ./local-check.yaml
  

  打开下载后的local-check.yaml，确认首行openapi: "3.0.1"存在且格式正确

2. 本地开发阶段改用本地文件加载 #

本地调试时无需依赖S3，直接修改SAM模板中RestApi的DefinitionBody，引用本地swagger.yaml：

Resources:
  RestApi:
    Type: AWS::Serverless::Api
    Properties:
      # 其他配置...
      DefinitionBody:
        Fn::Transform:
          Name: AWS::Include
          Parameters:
            Location: ./swagger.yaml

部署到AWS时再改回S3路径即可

3. 校验Swagger文件格式 #

确保swagger.yaml无语法错误，无编码问题（需为UTF-8无BOM格式），可以用openapi-cli工具本地校验：

npm install -g @redocly/openapi-cli
openapi validate swagger.yaml

二、AWS SAM本地测试流程 #

1. 环境准备 #

确保已安装：

• AWS SAM CLI
• Node.js 18.x（与函数Runtime版本一致）
• AWS CLI（配置本地开发凭证）

2. 启动本地API与Lambda函数 #

在项目根目录执行：

sam local start-api

命令会自动构建Node.js函数，启动本地API网关（默认端口3000），并将API请求映射到本地Lambda函数

3. 测试API端点 #

用curl或Postman发送请求：

curl http://localhost:3000/api/v1/ecovision/packaging

验证函数返回是否符合预期

三、本地运行Swagger UI #

方法1：利用SAM CLI自带支持 #

启动本地API时，若Swagger定义加载正常，SAM会自动在http://localhost:3000/swagger提供Swagger UI界面。若未自动生成，可显式指定Swagger文件启动：

sam local start-api --swagger swagger.yaml

方法2：独立部署Swagger UI #

1. 获取Swagger UI静态资源包，解压得到dist目录
2. 将你的swagger.yaml复制到dist目录下
3. 修改dist/index.html中的url参数为./swagger.yaml
4. 用本地HTTP服务器启动dist目录（以Node.js的http-server为例）：

   npx http-server ./dist -p 8080
   

   访问http://localhost:8080即可查看Swagger UI

附：你提供的配置文件 #

swagger.yaml

openapi: "3.0.1"
info:
  title: "EcoVision Service API"
  description: "EcoVision service apis"
  contact:
    name: "Product Technology - Sourcing team"
    email: "supplierportalsupport@kmart.com.au"
  termsOfService: "https://www.kmart.com.au"
  version: "v1.0"

paths:
  /api/v1/ecovision/packaging:
    get:
      summary: Retrieve resources
      responses:
        200:
          description: Successful response

AWS SAM模板

AWSTemplateFormatVersion: 2010-09-09
Description: >-
  sourcing-ecovision-backend

Transform:
  - AWS::Serverless-2016-10-31

Globals:
  Function:
    Timeout: 3
    MemorySize: 128
    Architectures:
      - x86_64

    Tracing: Active
    Tags:
      stage:
        Ref: StageName
  Api:
    OpenApiVersion: '3.0.1'
    TracingEnabled: true

Parameters:
  S3BucketName:
    Type: String
    Description: The name of the S3 bucket in which the Swagger specification is stored
  StageName:
    Type: String
    Description: The name of the stage, e.g. "dev", "preprod", "prod"
    Default: dev

Resources:
  RestApi:
    Type: AWS::Serverless::Api
    Properties:
      Name:
        Fn::Sub: todo-app-api-${StageName}
      StageName:
        Ref: StageName
      DefinitionBody:
        Fn::Transform:
          Name: AWS::Include
          Parameters:
            Location:
              Fn::Join:
                - ""
                - - "s3://"
                  - Ref: S3BucketName
                  - "/swagger.yaml"

  getAllPackagingMaterialFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/handlers/packaging/
      Handler: packagingHandler.getAllPackagingMaterial
      Runtime: nodejs18.x
      Events:
        Api:
          Type: Api
          Properties:
            Path: /api/v1/ecovision/packaging
            Method: GET
    Metadata:
      BuildMethod: esbuild
      BuildProperties:
        Minify: true
        Target: es2020
        EntryPoints:
          - src/handlers/packaging/packagingHandler.ts

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