嵌套模型和自定义架构 ID 时无法解析指针：/components/schemas

Question

我在用Swashbuckle.AspNetCore 6.4.0

我使用垂直切片方法，其中嵌套模型和类具有相同的名称Command。

因为 swagger 检查模型名称以生成架构，所以我必须将其添加到 swagger gen 选项中

c.CustomSchemaIds(x => x.FullName);

但现在我的架构已损坏，尽管显示端点，但架构没有显示任何内容。我还可以在页面顶部看到此错误：

Resolver error at paths./api/agents/{aggregateId}/enrolments.post.requestBody.content.application/json.schema.$ref
Could not resolve reference: Could not resolve pointer: /components/schemas/MyProject.Features.EnrolAgent+Command does not exist in document
Resolver error at paths./api/agents/{aggregateId}/enrolments.post.requestBody.content.text/json.schema.$ref
Could not resolve reference: Could not resolve pointer: /components/schemas/MyProject.Features.EnrolAgent+Command does not exist in document
Resolver error at paths./api/agents/{aggregateId}/enrolments.post.requestBody.content.application/*+json.schema.$ref
Could not resolve reference: Could not resolve pointer: /components/schemas/MyProject.Features.EnrolAgent+Command does not exist in document
Resolver error at paths./api/clients.post.requestBody.content.application/json.schema.$ref
Could not resolve reference: Could not resolve pointer: /components/schemas/MyProject.Features.CreateClient+Command does not exist in document
Resolver error at paths./api/clients.post.requestBody.content.text/json.schema.$ref
Could not resolve reference: Could not resolve pointer: /components/schemas/MyProject.Features.CreateClient+Command does not exist in document
Resolver error at paths./api/clients.post.requestBody.content.application/*+json.schema.$ref
Could not resolve reference: Could not resolve pointer: /components/schemas/MyProject.Features.CreateClient+Command does not exist in document
MyProject.Features.EnrolAgent+Command does not exist in document

我如何让嵌套模型根据 xml 注释生成正确的架构？

这是我的代码

public class EnrolAgent
{
    private static readonly ILogger Logger = LoggerFactory.CreateLogger<EnrolAgent>();

    public class Command
        : ICommand
    {
        /// <summary>
        /// The optional message Id. If empty it will be generated at server side
        /// </summary>
        /// <example>00000000-0000-0000-0000-000000000000</example>
        public Guid MessageId { get; init; }
        
        /// <summary>
        /// The agent's Id
        /// </summary>
        /// <example>00000000-0000-0000-0000-000000000000</example>
        public Guid AggregateId { get; init; }
        
        /// <summary>
        /// The language codes supported in ISO 639-1
        /// </summary>
        /// <example>["00000000-0000-0000-0000-000000000001", "00000000-0000-0000-0000-000000000002"]</example>
        public IEnumerable<Guid> BrandIds { get; init; } = Enumerable.Empty<Guid>();

        public override string ToString()
        {
            return this.DisplayInfo();
        }
    }
    
    public class Handler
        : ICommandHandler<Command>
    {
        private readonly IDomainEventsConsumer _domainEventsConsumer;
        private readonly IDateTimeFactory _dateTimeFactory;
        private readonly IAggregateRepository<AgentAggregate> _agentRepository;

        public Handler(
            IDomainEventsConsumer domainEventsConsumer,
            IDateTimeFactory dateTimeFactory,
            IAggregateRepository<AgentAggregate> agentRepository)
        {
            _domainEventsConsumer = domainEventsConsumer;
            _dateTimeFactory = dateTimeFactory;
            _agentRepository = agentRepository;
        }
        
        public async Task<CommandResult> Handle(Command command)
        {
            Logger.LogDebug($"Handling command {command}");
            var aggregateId = command.AggregateId;
            
            var agent = await _agentRepository.Get(aggregateId);
            var createdOn = _dateTimeFactory.CreateUtcNow();
            
            agent.Enrol(createdOn, command.BrandIds);
            
            var domainEvents = await agent.ConsumeDomainEventChanges(_domainEventsConsumer);
            
            var commandResult = CommandResult.Create(aggregateId, domainEvents);
            return commandResult;
        }
    }
}

这就是我配置 swagger 的方式

private static IServiceCollection AddOpenApi(this IServiceCollection services, IEnumerable<Assembly> allAssemblies)
{
    var mainAssemblyName = typeof(Startup).Assembly.GetName().Name;

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = mainAssemblyName, 
            Version = "v1",
            Description = "Sample",
        });
        
        c.DocumentFilter<LowerCaseDocumentFilter>();
            
        var xmlCommentsWebApi = Path.Combine(AppContext.BaseDirectory, $"{mainAssemblyName}.xml");
        c.IncludeXmlComments(xmlCommentsWebApi);
        
        var allApplicationAssemblies =
            allAssemblies
                .Where(x => x.GetTypes().Any(t => typeof(ICommand).IsAssignableFrom(t) && !t.IsInterface && !t.IsAbstract))
                .ToList();
        
        foreach (var applicationAssembly in allApplicationAssemblies)
        {
            var xmlCommentsApplication = Path.Combine(AppContext.BaseDirectory, $"{applicationAssembly.GetName().Name}.xml");
            c.IncludeXmlComments(xmlCommentsApplication);
        }
        
        // It fixes problem when using Command to name different nested commands
        c.CustomSchemaIds(x => x.FullName);
        
        c.AddSecurityDefinition(
            "Bearer",
            new OpenApiSecurityScheme
            {
                Name = "Authorization",
                Type = SecuritySchemeType.Http,
                Scheme = "Bearer",
                In = ParameterLocation.Header,
                Description = "JWT Authorization header"
            });

        c.AddSecurityRequirement(
            new OpenApiSecurityRequirement()
            {
                {
                    new OpenApiSecurityScheme
                    {
                        Reference = new OpenApiReference()
                        {
                            Type = ReferenceType.SecurityScheme,
                            Id = "Bearer"
                        }
                    },
                    new string[]{}
                }
            });
    });
        
    return services;
}

Answer 1

我用它修复了

c.CustomSchemaIds(s => s.FullName?.Replace("+", "."));

根据https://github.com/swagger-api/swagger-ui/issues/7911