AWS SDK for JavaScript v3 中导出 YAML OpenAPI 规范的 Bug 解析

问题背景

在使用 AWS SDK for JavaScript v3 时，开发者发现通过 GetExportCommand 导出 OpenAPI 3.0 规范时，即使明确指定了 YAML 格式，仍然只能获取 JSON 格式的输出。这个问题在 AWS CLI 中不存在，CLI 可以正确导出 YAML 格式。

问题复现

开发者提供了以下代码示例来复现这个问题：

const getApiExportCommand = new GetExportCommand({
  restApiId: restApiId,
  stageName: stageName,
  exportType: 'oas30',
  accepts: 'application/yaml',
})

const APIGATEWAY_CLIENT = new APIGatewayClient({})
APIGATEWAY_CLIENT.send(getApiExportCommand).then((result) => {
  console.log(Buffer.from(result.body).toString('utf8'))
}).catch(console.error)

问题分析

AWS 团队对此问题进行了深入调查，发现：

1. 在 AWS CLI 中，相同的参数可以正确导出 YAML 格式
2. 在 JavaScript SDK v2 版本中也能正确导出 YAML
3. 但在 JavaScript SDK v3 版本中，即使指定了 YAML 格式，返回的仍然是 JSON 格式

技术细节

从团队提供的测试结果可以看出：

• 在 v2 版本中，返回的 contentDisposition 正确显示为 YAML 文件
• 在 v3 版本中，虽然请求参数相同，但返回的 contentDisposition 却显示为 JSON 文件
• 实际返回的内容体也是 JSON 格式而非请求的 YAML 格式

解决方案

AWS 团队确认这是一个 bug，并在版本 3.580.0 中进行了修复。这个版本于 2024 年 5 月 21 日正式发布。

开发者验证

有开发者反馈在升级到 3.580.0 版本后问题仍然存在，这表明：

1. 可能需要检查 SDK 版本是否正确升级
2. 可能需要清除缓存或重新安装依赖
3. 如果问题持续存在，可能需要进一步调查特定环境下的兼容性问题

总结

这个案例展示了 SDK 版本间行为不一致的问题，提醒开发者在遇到类似问题时：

1. 首先确认问题是否在不同版本间表现不同
2. 检查最新版本是否已修复
3. 如果问题在新版本中仍然存在，需要提供更多环境信息以便进一步调查

AWS SDK 团队对此类问题的响应速度值得肯定，开发者可以放心报告遇到的任何兼容性问题。