如何为CommunityToolkit.Datasync框架配置SwaggerUI生成POST参数文档

问题根源在于TableController<TEntity>的CreateAsync方法使用泛型参数TEntity，Swagger默认无法自动解析泛型类型对应的具体实体（如Ship）的字段结构，导致POST接口文档中看不到Name和Operational的输入项，但接口本身逻辑正常。

以下是两种实用的解决办法：

方法一：显式重载CreateAsync方法（推荐） #

在你的ShipController中重载父类的CreateAsync方法，直接使用具体的Ship类型作为参数，Swagger会自动识别实体字段并生成文档：

[HttpPost]
public override async Task<IActionResult> CreateAsync(Ship entity)
{
    // 直接调用父类实现，无需额外逻辑
    return await base.CreateAsync(entity);
}

重启API后，Swagger UI的POST接口就能显示Ship的Name（字符串类型）和Operational（布尔类型）输入项了。

方法二：配置Swagger手动映射泛型实体Schema #

如果不想为每个实体控制器都重载方法，可以在Swagger配置中手动指定泛型对应的实体结构：

1. 先确保你的API项目启用了XML文档生成（项目属性→生成→勾选"XML文档文件"）。
2. 在Program.cs中修改Swagger配置：

builder.Services.AddSwaggerGen(c =>
{
    // 加载项目XML注释文件
    var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    c.IncludeXmlComments(xmlFilePath);

    // 为Ship实体手动定义Swagger Schema
    c.MapType<Ship>(() => new OpenApiSchema
    {
        Type = "object",
        Required = new HashSet<string> { "Name" }, // 如果Name是必填项
        Properties = new Dictionary<string, OpenApiProperty>
        {
            ["Name"] = new OpenApiProperty 
            { 
                Type = "string", 
                Description = "Ship's name" 
            },
            ["Operational"] = new OpenApiProperty 
            { 
                Type = "boolean", 
                Description = "Whether the ship is operational" 
            }
        }
    });
});

这种方法需要手动维护每个实体的Schema，适合实体较少的场景。

验证：完成配置后重启API，Swagger UI的POST接口即可正常显示Ship的参数输入项，Avalonia客户端和管理网站可以直接复用Swagger生成的API文档或客户端代码。

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