Swift OpenAPI Generator 中 OpenAPI 3.1.0 二进制文件上传的注意事项

在 Swift OpenAPI Generator 项目中，开发者在使用 OpenAPI 3.1.0 规范处理文件上传时可能会遇到一个常见问题：当定义 multipart 请求中包含二进制文件部分时，生成的服务端代码会错误地期望 text/plain 内容类型而不是 application/octet-stream。

这个问题的根源在于 OpenAPI 3.1.0 规范对文件上传处理方式的改变。在 3.0.0 版本中，使用 format: binary 可以正确指定二进制内容类型，但在 3.1.0 版本中，规范引入了更明确的 contentEncoding 关键字来处理内容编码问题。

OpenAPI 3.1.0 明确表示 format 关键字不再影响模式的内容编码。相反，JSON Schema 提供了 contentEncoding 关键字，专门用于指定模式的内容编码。这一变化使得 API 定义更加清晰和符合标准。

对于开发者来说，解决方案很简单：在 OpenAPI 3.1.0 规范中，应该使用 contentEncoding: binary 而不是 format: binary 来定义二进制文件部分。这样生成的代码就会正确期望 application/octet-stream 内容类型。

这种变化反映了 OpenAPI 规范向更精确、更符合 JSON Schema 标准的方向发展。开发者需要注意不同版本间的这些细微但重要的差异，特别是在处理文件上传等特殊场景时。

在实际开发中，当升级到 OpenAPI 3.1.0 时，建议全面检查所有涉及二进制数据传输的 API 定义，确保使用了正确的内容编码声明方式。这不仅会影响内容类型的验证，还可能影响后续的数据处理流程。