Swift-OpenAPI-Generator 中关于 DELETE 请求响应定义的必要性

在 OpenAPI 规范中，每个操作（operation）都必须定义至少一个响应。这一要求在实际开发中经常被忽视，特别是在处理 DELETE 请求时，开发者可能会认为不需要定义响应内容。

问题背景

当使用 Swift-OpenAPI-Generator 工具生成代码时，如果 DELETE 路径没有定义任何响应内容，工具会抛出错误："Expected responses value for the DELETE endpoint... to be parsable as Mapping but it was not"。这个错误明确指出了问题所在 - 缺少必要的响应定义。

OpenAPI 规范要求

根据 OpenAPI 3.1.0 规范，每个操作都必须包含 Responses 对象，该对象至少要定义一个成功的响应或默认响应。即使 DELETE 操作通常只返回状态码而不返回内容体，仍然需要在规范中明确定义这些状态码。

正确的 DELETE 操作定义示例

一个规范的 DELETE 操作应该像这样定义响应：

"responses": {
    "204": {
        "description": "No content, indicating successful deletion."
    },
    "400": {
        "description": "Bad request, the request was unacceptable."
    },
    "404": {
        "description": "Not Found, the resource to be deleted does not exist."
    },
    "403": {
        "description": "Forbidden, the user does not have the necessary permissions."
    }
}

为什么需要定义响应

1. API 文档完整性：明确定义的响应帮助开发者理解 API 的行为
2. 代码生成准确性：工具需要这些信息来生成正确的客户端和服务端代码
3. 错误处理：预先定义的错误响应让客户端能够正确处理各种情况
4. 规范合规性：遵循 OpenAPI 规范确保与其他工具的兼容性

最佳实践建议

即使是最简单的 DELETE 操作，也建议至少定义以下响应：

• 204 No Content（成功删除）
• 404 Not Found（资源不存在）
• 403 Forbidden（权限不足）

这种做法不仅符合规范要求，还能提高 API 的可用性和可维护性。