在Dedoc/Scramble中实现自定义错误响应体的文档化

在API开发中，统一错误响应格式对于前端开发者来说至关重要。Dedoc/Scramble作为一款Laravel API文档生成工具，提供了强大的文档生成能力，但在处理自定义错误响应体时，开发者可能会遇到一些困惑。

自定义错误响应的常见需求

现代API开发通常会对错误响应进行统一包装，返回结构化的错误信息。典型的自定义错误响应可能包含以下字段：

• success: 表示请求是否成功的布尔值
• status: HTTP状态码
• message: 人类可读的错误信息
• body: 可能为null或包含额外错误详情

实现自定义错误响应

在Laravel中，我们可以通过自定义异常类来实现统一的错误响应格式。例如：

class NotFoundException extends NotFoundHttpException 
{
    public function render(): JsonResponse
    {
        $response = new WrapResponse(
            body: null,
            success: false,
            status: 404,
            message: $this->getMessage()
        );

        return response()->json($response->toArray(), 404);
    }
}

在Scramble中文档化自定义错误响应

Scramble提供了@response标签来文档化API响应。对于自定义错误响应，我们可以这样使用：

/**
 * @param string $id
 * @return Response
 * @throws NotFoundException
 * @response 404 array{"success": false, "status": 404, "message": "Resource not found", "body": null}
 */

这种语法使用了PHP的类型声明格式，清晰地定义了404错误时的响应体结构。

最佳实践建议

1. 保持一致性：所有错误响应应遵循相同的结构，便于前端处理
2. 详细文档：为每种可能的错误状态码添加文档说明
3. 考虑使用DTO：可以创建专门的响应DTO类，确保文档与实际代码一致
4. 覆盖常见错误：除了404，还应考虑400、401、403、500等常见错误状态

进阶技巧

对于更复杂的场景，可以考虑：

1. 使用继承：创建基础错误响应类，其他错误类继承它
2. 多语言支持：在message字段中支持多语言错误信息
3. 错误代码：添加error_code字段，便于前端精确识别错误类型
4. 链接文档：在响应中包含help_link字段，指向更详细的错误说明

通过合理使用Scramble的文档功能，可以生成清晰、准确的API文档，极大提升前后端协作效率。