.NET 9升级：为所有接口添加错误响应类型及OpenAPI适配

一、基础升级步骤 #

• 修改项目文件（.csproj）的目标框架版本为 net9.0：

  <TargetFramework>net9.0</TargetFramework>
  

• 卸载原Swagger相关第三方NuGet包（如Swashbuckle.AspNetCore），.NET 9已内置OpenAPI支持，无需依赖第三方库
• 确保开发及部署环境安装.NET 9 SDK

二、适配自定义错误响应逻辑 #

.NET 9 内置的OpenAPI体系使用IOpenApiOperationProcessor替代原Swashbuckle的IOperationProcessor，以下是具体适配方案：

1. 实现自定义OpenAPI操作处理器 #

创建处理器类，通过ProcessAsync方法为所有端点添加通用错误响应：

using Microsoft.AspNetCore.OpenApi;
using Microsoft.AspNetCore.OpenApi.Models;
using Microsoft.AspNetCore.OpenApi.Processors;

public class AddErrorResponseProcessor : IOpenApiOperationProcessor
{
    public async ValueTask<bool> ProcessAsync(OpenApiOperationProcessorContext context)
    {
        // 定义通用错误响应模型的媒体类型
        var jsonMediaType = new OpenApiMediaType
        {
            Schema = context.SchemaGenerator.GenerateSchema(typeof(ErrorResponse), context.SchemaRepository)
        };

        // 添加500服务器内部错误响应
        context.Operation.Responses.TryAdd("500", new OpenApiResponse
        {
            Description = "服务器内部错误",
            Content = new Dictionary<string, OpenApiMediaType> { ["application/json"] = jsonMediaType }
        });

        // 添加400请求参数错误响应
        context.Operation.Responses.TryAdd("400", new OpenApiResponse
        {
            Description = "请求参数验证失败",
            Content = new Dictionary<string, OpenApiMediaType> { ["application/json"] = jsonMediaType }
        });

        return await ValueTask.FromResult(true);
    }
}

// 通用错误响应模型
public class ErrorResponse
{
    public int StatusCode { get; set; }
    public string Message { get; set; } = string.Empty;
    public IEnumerable<string>? Details { get; set; }
}

2. 注册自定义处理器与配置OpenAPI #

在Program.cs的服务配置中，替换原Swagger注册逻辑：

builder.Services.AddOpenApi(options =>
{
    // 配置文档基础信息
    options.AddDocumentTransformer(doc =>
    {
        doc.Info = new OpenApiInfo
        {
            Title = "业务API文档",
            Version = "v1",
            Description = ".NET 9 升级后的OpenAPI规范文档"
        };
    });

    // 注册自定义错误响应处理器
    options.OperationProcessors.Add<AddErrorResponseProcessor>();
});

3. 映射OpenAPI端点与Swagger UI #

在Program.cs中间件配置段，替换原Swagger中间件：

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    // 映射OpenAPI文档并启用Swagger UI，默认访问地址为 /swagger
    app.MapOpenApi().WithSwaggerUi();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

三、关键注意事项 #

• 原Swashbuckle的注解（如[SwaggerOperation]）需替换为.NET 9内置的[OpenApiOperation]、[OpenApiParameter]等注解
• 多文档需求可通过AddOpenApi配置多个文档实例，再通过MapOpenApi("文档名称")分别映射
• 生产环境可根据需求关闭Swagger UI，仅保留OpenAPI文档接口

内容的提问来源于stack exchange，提问作者Dawood Awan