openapi-typescript 中 SuccessResponseJSON 和 ErrorResponseJSON 的类型问题解析

在 openapi-typescript 7.1.0 版本中，开发者发现了一个关于 SuccessResponseJSON 和 ErrorResponseJSON 类型的潜在问题。这两个辅助类型在实际使用时会返回 never 类型，而不是预期的响应类型。

问题背景

openapi-typescript 是一个将 OpenAPI/Swagger 规范转换为 TypeScript 类型的工具。它提供了一些辅助类型来帮助开发者更方便地处理 API 响应。其中 SuccessResponseJSON 和 ErrorResponseJSON 是专门用于处理 JSON 格式响应的类型。

问题分析

在 v7 版本中，核心类型 SuccessResponse 和 ErrorResponse 的实现发生了变化，但它们的 JSON 专用版本 SuccessResponseJSON 和 ErrorResponseJSON 没有相应更新。这导致了类型系统无法正确推断出 JSON 格式的响应类型。

原实现使用了 FilterKeys 来筛选包含 "/json" 后缀的响应类型，而新版本应该改为直接使用 ${string}/json 作为内容类型标识。

技术细节

正确的实现应该是：

export type JSONLike = `${string}/json`;

export type SuccessResponseJSON<PathMethod> = SuccessResponse<ResponseObjectMap<PathMethod>, JSONLike>;

这种实现方式更符合 v7 版本的架构设计，能够正确地提取出 JSON 格式的响应类型。

影响范围

这个问题会影响所有使用 SuccessResponseJSON 或 ErrorResponseJSON 类型来处理 API 响应的代码。开发者会发现这些类型总是返回 never，无法正确推断出实际的响应类型。

解决方案

对于遇到此问题的开发者，可以采取以下临时解决方案：

1. 直接使用 SuccessResponse 类型并手动指定内容类型
2. 在本地项目中重新定义这些辅助类型
3. 等待官方修复并升级版本

最佳实践

在处理 OpenAPI 生成的类型时，建议开发者：

1. 始终检查辅助类型的实际推断结果
2. 对于关键的类型操作，考虑编写自定义类型工具
3. 保持对库版本更新的关注，及时适配类型系统的变化

这个问题虽然不影响核心功能，但对于依赖这些辅助类型的代码来说是一个需要注意的兼容性问题。开发者可以根据项目需求选择临时解决方案或等待官方修复。