OpenAPI-TS 项目中请求响应模型生成问题的深度解析

在基于 OpenAPI 规范的前端代码生成过程中，一个常见但容易被忽视的问题是：当 API 接口的请求和响应使用相同 Schema 但通过 readOnly/writeOnly 属性区分不同字段时，代码生成工具能否正确识别并生成独立的类型定义。本文将以 openapi-ts 项目为例，深入分析这一技术问题及其解决方案。

问题现象

在典型的认证场景中，我们经常会遇到这样的数据结构设计：

• 请求体需要提交 email 和 password 字段
• 响应体则返回 access 和 refresh token 字段

在 OpenAPI 规范中，规范的写法是通过同一个 Schema 定义，但使用 writeOnly 和 readOnly 属性来区分字段的读写方向：

"TokenObtainPair": {
  "properties": {
    "email": {"type": "string", "writeOnly": true},
    "password": {"type": "string", "writeOnly": true},
    "access": {"type": "string", "readOnly": true},
    "refresh": {"type": "string", "readOnly": true}
  }
}

理想情况下，代码生成工具应该自动生成：

• 请求类型：只包含 email 和 password
• 响应类型：只包含 access 和 refresh

但实际生成的类型定义却混合了所有字段，导致类型系统无法正确反映 API 的实际约束。

技术背景

OpenAPI 3.0 规范明确支持通过 readOnly 和 writeOnly 属性来定义字段的传输方向：

• readOnly=true：仅出现在响应中
• writeOnly=true：仅出现在请求中
• 两者都为 false：双向传输

这种设计在 RESTful API 中非常常见，特别是在以下场景：

1. 认证令牌的获取与刷新
2. 包含敏感信息的创建/更新操作
3. 包含计算字段的查询响应

解决方案分析

在 openapi-ts 项目中，这个问题已被识别并修复。其核心解决思路是：

1. Schema 预处理阶段识别 readOnly/writeOnly 标记
2. 根据操作类型（请求/响应）过滤相应字段
3. 生成独立的接口类型定义

修复后的类型生成结果应该类似：

// 请求类型
type TokenObtainPairRequest = {
  email: string;
  password: string;
};

// 响应类型 
type TokenObtainPairResponse = {
  access: string;
  refresh: string;
};

最佳实践建议

对于开发者使用 openapi-ts 或其他代码生成工具时，建议：

1. 始终明确定义字段的 readOnly/writeOnly 属性
2. 验证生成的类型是否正确地分离了请求/响应模型
3. 在复杂场景中考虑手动定义类型补充
4. 定期更新生成工具以获取最新修复

总结

OpenAPI 规范中的读写控制属性是 API 设计的重要特性，代码生成工具对其的正确支持关系到类型系统的准确性。通过 openapi-ts 项目的这一修复案例，我们可以看到现代 API 开发工具链正在不断完善对 OpenAPI 规范的支持深度，为开发者提供更精准的类型安全保证。