跳到主要内容

4.7 Problem Details 与 OpenAPI

Problem Details 提供标准化错误响应格式，OpenAPI 提供机器可读接口文档。它们一起帮助前后端稳定协作、自动生成客户端、减少口头约定。

学习目标​

  • 能解释 Problem Details 的核心字段。
  • 能在 API 中返回标准错误响应。
  • 能为接口生成 OpenAPI 文档。
  • 能理解 OpenAPI 对前端类型生成的价值。

应用场景​

  • 表单校验失败时返回字段错误。
  • 统一处理 404、400、500 等失败响应。
  • 前端根据 OpenAPI 生成 TypeScript 类型。
  • 用 Swagger UI 手工调试接口。

Problem Details 字段​

字段说明
type错误类型文档地址或稳定标识
title简短错误标题
statusHTTP 状态码
detail面向调用方的详细说明
instance当前请求或资源路径

示例：返回校验错误​

app.MapPost("/todos", async (
    CreateTodoRequest request,
    TodoService service,
    CancellationToken cancellationToken) =>
{
    var errors = request.Validate();
    if (errors.Count > 0)
    {
        return Results.ValidationProblem(errors);
    }

    var todo = await service.CreateAsync(request, cancellationToken);
    return Results.Created($"/todos/{todo.Id}", todo);
});

OpenAPI 示例​

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.MapPost("/todos", CreateTodoAsync)
    .WithName("CreateTodo")
    .WithSummary("创建任务")
    .Produces<TodoDto>(StatusCodes.Status201Created)
    .ProducesValidationProblem();

重点难点​

  • OpenAPI 文档要反映真实响应，不要只写成功路径。
  • 错误格式标准化后，前端可以做统一错误处理。
  • Problem Details 是格式标准，不替代业务错误码设计。
  • 生产环境是否开放 Swagger UI 要结合安全策略决定。

常见误区​

误区推荐做法
只文档化 200 响应同时声明 400、401、403、404、500
Swagger 能打开就算完成确保 DTO、状态码、错误格式准确
每个接口自定义错误 JSON使用统一 Problem Details 或扩展格式

练习​

  • 给任务创建接口添加 ProducesValidationProblem。
  • 给 404 返回 Problem Details。
  • 用 OpenAPI 文档检查前端 API Client 的类型是否一致。

延伸阅读​

  • RFC 9457 Problem Details。
  • ASP.NET Core OpenAPI。
  • Swagger UI 与客户端生成。