ASP.NET Core无需将DTO作为请求参数，如何为Swagger声明自定义OpenAPI类型

有两种简便方法可以实现你的需求，无需手动创建Schema或修改请求处理逻辑：

方法1：使用Swashbuckle注释特性（推荐） #

这种方法通过Swashbuckle提供的注释特性直接指定请求体类型，不需要在Action中添加多余参数：

1. 首先安装Swashbuckle.AspNetCore.Annotations NuGet包：

Install-Package Swashbuckle.AspNetCore.Annotations

2. 在Program.cs（或Startup.cs）中启用Swagger注释支持：

builder.Services.AddSwaggerGen(c =>
{
    // 启用注释特性
    c.EnableAnnotations();
});

3. 在Action上添加[OpenApiRequestBody]特性，指定你的DTO类型和请求内容类型：

using Swashbuckle.AspNetCore.Annotations;

[HttpPost]
[Route("api/upload")]
[Consumes("multipart/form-data")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
// 直接指定请求体对应的DTO类型
[OpenApiRequestBody(contentType: "multipart/form-data", bodyType: typeof(SomeDTO))]
public async Task<IActionResult> UploadDataAsync()
{
    // 使用HttpContext.Request.Body手动读取请求体的逻辑
    return NoContent();
}

这样Swagger文档会自动生成SomeDTO对应的请求体结构，完全不影响你手动处理请求体的逻辑。

方法2：添加占位参数并标记为不绑定 #

如果不想额外安装包，可以添加一个占位参数，用[BindNever]标记让模型绑定忽略它，同时让Swagger识别该参数作为请求体类型：

[HttpPost]
[Route("api/upload")]
[Consumes("multipart/form-data")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
// 添加占位参数，用BindNever标记避免模型绑定
public async Task<IActionResult> UploadDataAsync([FromForm, BindNever] SomeDTO _)
{
    // 使用HttpContext.Request.Body手动读取请求体的逻辑
    return NoContent();
}

这里的下划线_是占位符命名，明确表示该参数不会被使用。[BindNever]会告知ASP.NET Core不要尝试绑定这个参数，因此不会和你手动读取RequestBody的逻辑冲突，而Swagger会根据SomeDTO生成对应的请求体文档。

两种方法都不需要手动构建Schema，都是利用Swashbuckle自动生成DTO的OpenAPI定义，满足你保持API文档准确性的需求。

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