Azure Function中Swagger UI出现Could not resolve reference错误求助

问题根源 #

• 不同类的属性使用了相同的JsonProperty("campos")标记，但对应类型不同（CampoCliente和CampoAtributo），导致Swagger Schema生成逻辑混淆，无法解析引用。
• CampoAtributo类未被自动纳入Swagger Schema定义，进一步引发引用失败。

可行解决方案 #

1. 显式注册缺失的Schema类型 #

在Program.cs的Swagger配置中，手动将CampoAtributo添加到Schema生成列表，确保Swagger识别该类型：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "MyFunctionAPI", Version = "v1" });
    // 启用XML注释（需先在项目生成设置中勾选XML文档文件）
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
    
    // 手动注册CampoAtributo的Schema
    c.MapType<CampoAtributo>(() => new OpenApiSchema
    {
        Type = "object",
        Properties = new Dictionary<string, OpenApiSchema>
        {
            { "campos", new OpenApiSchema { Type = "string" } }
        }
    });
});

2. 自定义Schema过滤器区分同名JsonProperty #

创建自定义ISchemaFilter，为不同类下的campos属性生成唯一的Schema引用，避免命名冲突：

public class CustomSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        switch (context.Type.Name)
        {
            case nameof(OtroAtributo):
                var campoAtriSchema = context.SchemaGenerator.GenerateSchema(typeof(CampoAtributo), context.SchemaRepository);
                schema.Properties["campos"] = new OpenApiSchema
                {
                    Reference = new OpenApiReference { Id = nameof(CampoAtributo), Type = ReferenceType.Schema }
                };
                if (!context.SchemaRepository.Schemas.ContainsKey(nameof(CampoAtributo)))
                {
                    context.SchemaRepository.Schemas.Add(nameof(CampoAtributo), campoAtriSchema);
                }
                break;
            case nameof(Cliente):
                var campoClienteSchema = context.SchemaGenerator.GenerateSchema(typeof(CampoCliente), context.SchemaRepository);
                schema.Properties["campos"] = new OpenApiSchema
                {
                    Reference = new OpenApiReference { Id = nameof(CampoCliente), Type = ReferenceType.Schema }
                };
                if (!context.SchemaRepository.Schemas.ContainsKey(nameof(CampoCliente)))
                {
                    context.SchemaRepository.Schemas.Add(nameof(CampoCliente), campoClienteSchema);
                }
                break;
        }
    }
}

在Program.cs中注册该过滤器：

builder.Services.AddSwaggerGen(c =>
{
    // 其他配置...
    c.SchemaFilter<CustomSchemaFilter>();
});

3. 手动定义OpenAPI请求体结构 #

在Function的OpenApiRequestBody属性中，直接使用OpenApiSchema手动定义请求体，绕过自动生成的冲突：

[OpenApiOperation("MyFunction", new[] { "Items" }, Description = "demo")]
[OpenApiRequestBody("application/json", 
    new OpenApiSchema
    {
        Type = "object",
        Properties = new Dictionary<string, OpenApiSchema>
        {
            { "campos", new OpenApiSchema { Reference = new OpenApiReference { Id = nameof(CampoCliente), Type = ReferenceType.Schema } } },
            { "attr", new OpenApiSchema { Reference = new OpenApiReference { Id = nameof(OtroAtributo), Type = ReferenceType.Schema } } }
        },
        Required = new HashSet<string> { "campos", "attr" }
    }, 
    Required = true, Description = "demo")]
[Function(nameof(MyFunction))]
public HttpResponseData MyFunction([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req)
{
    _logger.LogInformation("C# HTTP trigger function processed a request.");
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString("Welcome to Azure Functions!");
    return response;
}

4. 验证Swagger生成结果 #

启动Function后，访问Swagger UI，检查swagger.json是否包含CampoAtributo、CampoCliente等类型的Schema定义，且Cliente和OtroAtributo下的campos属性分别指向正确的Schema引用。

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