如何在非标准Web API控制器中使用NSwag处理动态参数？

没问题！你这种通过读取Request.Content+dynamic解析参数的写法，确实会让NSwag抓不到请求体的结构信息，导致生成的API文档缺失请求参数部分。不过完全可以通过添加NSwag提供的属性来手动补充元数据，让它正常生成完整的文档，下面给你几个可行的方案：

方案1：定义DTO类 + 使用[SwaggerRequestBody]属性（推荐） #

这是最规范也最易维护的方式，先创建一个对应请求体结构的强类型DTO：

public class CreateAccountRequest
{
    // 可以加数据注解，让NSwag生成更详细的文档（比如必填、格式说明）
    [Required(ErrorMessage = "Please provide a valid email.")]
    [EmailAddress]
    public string Email { get; set; }

    [Required(ErrorMessage = "Please provide an account name.")]
    public string Name { get; set; }

    [Required(ErrorMessage = "Please provide a valid domain.")]
    public string Domain { get; set; }
}

然后在你的控制器方法上添加[SwaggerRequestBody]属性，指定请求体的类型和媒体类型：

[HttpPost]
[ActionName("create-account")]
// 告诉NSwag这个接口的请求体是CreateAccountRequest类型，JSON格式且必填
[SwaggerRequestBody("application/json", typeof(CreateAccountRequest), Required = true)]
// 还可以补充响应的元数据，让文档更完整
[SwaggerResponse(HttpStatusCode.BadRequest, typeof(ApiMessageResult), Description = "Missing or invalid required fields")]
[SwaggerResponse(HttpStatusCode.OK, typeof(/* 替换成你的成功返回类型 */), Description = "Account created successfully")]
public IHttpActionResult CreateAccount()
{
    // 你的现有解析代码可以保留，也可以改成直接用强类型对象（后面会说）
    var body = Request.Content.ReadAsStringAsync().Result;
    dynamic json = Utils.GetJsonBody(body);
    // ... 后续逻辑不变
}

这样NSwag就能根据DTO类生成请求体的完整文档，包括必填字段、数据格式等信息。

方案2：手动编写JSON Schema（无需DTO） #

如果暂时不想定义DTO，也可以直接在[SwaggerRequestBody]里手动写JSON Schema来描述请求体结构：

[HttpPost]
[ActionName("create-account")]
[SwaggerRequestBody("application/json", 
    Schema = @"{
        ""type"": ""object"",
        ""required"": [""email"", ""name"", ""domain""],
        ""properties"": {
            ""email"": { ""type"": ""string"", ""format"": ""email"" },
            ""name"": { ""type"": ""string"" },
            ""domain"": { ""type"": ""string"" }
        }
    }", 
    Required = true)]
public IHttpActionResult CreateAccount()
{
    // 现有代码不变
}

这种方式不用改太多现有代码，但Schema需要手动维护，后续字段变更容易遗漏，适合临时场景。

额外建议：改成强类型参数绑定（长期最优解） #

其实你完全可以抛弃手动解析dynamic的逻辑，让ASP.NET自动帮你绑定请求体到强类型对象，这样NSwag会自动识别请求体结构，根本不需要额外加属性，代码也更简洁：

[HttpPost]
[ActionName("create-account")]
public IHttpActionResult CreateAccount([FromBody] CreateAccountRequest request)
{
    // ASP.NET会自动验证必填字段，直接用ModelState判断即可
    if (!ModelState.IsValid)
    {
        // 这里可以返回自定义的ApiMessageResult，或者直接用BadRequest(ModelState)
        var errorMessage = ModelState.Values.SelectMany(v => v.Errors)
                                           .FirstOrDefault()?.ErrorMessage ?? "Invalid request data.";
        return Content(HttpStatusCode.BadRequest, errorMessage.AsApiMessageResult());
    }

    // 直接使用request.Email、request.Name、request.Domain即可
    // ... 后续业务逻辑
}

这种方式不仅让NSwag自动生成完美的文档，还能获得编译时类型检查、自动模型验证，减少手动解析的冗余代码，长期维护起来更轻松。

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