.NET 9 OpenAPI文档生成异常：$ref引用不符合RFC3986规范

问题场景 #

使用.NET 9结合OpenApi和Scalar.AspNetCore构建API文档，模型类定义如下：

public class OrderResponse
{
    public string Id { get; set; }
    public decimal Amount { get; set; }
    public List<Transaction>? Transactions { get; set; }
    public List<Item> Items { get; set; }
}

public class Transaction
{
    public string Id { get; set; }
    public List<Item> Items { get; set; }
}

public class Item
{
    public string Id { get; set; }
}

控制器中创建返回OrderResponse的接口，代码编译正常，但在验证OpenAPI JSON文件时出现语义错误：

Semantic error at components.schemas.OrderResponse.properties.items.items.$ref
$ref values must be RFC3986-compliant percent-encoded URIs

查看生成的OpenAPI文件，发现items字段的引用路径异常：

{
    "items":  
    {
        "type": "array",
        "items": {
                     "$ref": "#/components/schemas/#/properties/transactions/items/properties/items/items"
                 }
    }
}

文档UI显示正常，但无法通过NSwag生成客户端代码。

问题原因 #

这是.NET 9 OpenAPI生成器在处理**多个嵌套类包含同名集合属性（Items）**时的路径生成bug，自动生成的$ref路径出现嵌套错误，生成了不符合RFC3986规范的无效URI，导致验证失败和客户端生成工具无法解析。

解决方法 #

方法1：自定义Schema ID生成策略 #

在Program.cs中配置SwaggerGen，使用类的完整名称作为Schema ID，避免命名冲突：

builder.Services.AddSwaggerGen(options =>
{
    options.CustomSchemaIds(type => type.FullName);
});

方法2：显式指定Schema名称 #

给每个模型类添加[SwaggerSchema]特性，明确指定Schema的标题：

using Microsoft.OpenApi.Models;

[SwaggerSchema(Title = "OrderResponse")]
public class OrderResponse
{
    public string Id { get; set; }
    public decimal Amount { get; set; }
    public List<Transaction>? Transactions { get; set; }
    public List<Item> Items { get; set; }
}

[SwaggerSchema(Title = "Transaction")]
public class Transaction
{
    public string Id { get; set; }
    public List<Item> Items { get; set; }
}

[SwaggerSchema(Title = "Item")]
public class Item
{
    public string Id { get; set; }
}

方法3：确保集合属性初始化 #

将可空集合属性改为非空并初始化，避免生成器处理可空类型时出现异常：

public class OrderResponse
{
    // ... 其他属性
    public List<Transaction> Transactions { get; set; } = [];
}

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