FastEndpoints项目中的Swagger文档配置问题解析

问题背景

在使用FastEndpoints框架配置Swagger文档时，开发者可能会遇到"Fetch error"错误。这种情况通常发生在未正确设置Swagger文档名称(DocumentName)的情况下。本文将深入分析这个问题产生的原因，并提供正确的配置方法。

问题现象

当开发者尝试配置单一Swagger文档但未设置DocumentName属性时，Swagger UI界面会抛出"Fetch error"错误。示例代码如下：

builder.Services.SwaggerDocument(o =>
{
    o.DocumentSettings = s =>
    {
        // s.DocumentName = "My Api v1.0"; // 注释此行会导致错误
        s.Title = "My Api";
        s.Version = "v1.0";
    };
});

问题根源

这个问题的根本原因在于FastEndpoints框架的默认行为：

1. 当未显式设置DocumentName时，框架会使用默认值"v1"
2. 如果同时存在多个文档配置使用相同的DocumentName，会导致冲突
3. FastEndpoints已经移除了对Swashbuckle的支持，仅支持NSwag

正确配置方法

单一文档配置

对于只需要一个Swagger文档的情况，可以明确指定DocumentName：

builder.Services.SwaggerDocument(o =>
{
    o.DocumentSettings = s =>
    {
        s.DocumentName = "v1"; // 明确设置文档名称
        s.Title = "My Api";
        s.Version = "v1";
    };
});

多文档配置

如果需要配置多个API文档版本，必须确保每个文档都有唯一的DocumentName：

builder.Services
    .SwaggerDocument(o => // 第一个文档
    {
        o.DocumentSettings = s =>
        {
            s.DocumentName = "v1"; // 文档1名称
            s.Title = "My Api";
            s.Version = "v1";
        };
    })
    .SwaggerDocument(o => // 第二个文档
    {
        o.DocumentSettings = s =>
        {
            s.DocumentName = "v2"; // 文档2名称，必须唯一
            s.Title = "My Api";
            s.Version = "v2";
        };
    });

最佳实践建议

1. 始终显式设置DocumentName：即使只需要一个文档，也建议明确设置DocumentName，避免依赖默认值
2. 保持命名一致性：DocumentName和Version可以保持一致，便于管理
3. 避免空配置：不要添加空的SwaggerDocument()调用，这会创建默认的"v1"文档
4. 版本控制：对于API版本控制，建议使用语义化版本命名规范

总结

FastEndpoints框架通过NSwag提供Swagger支持，开发者在使用时需要注意文档命名的唯一性。通过正确配置DocumentName属性，可以避免"Fetch error"错误，并实现灵活的API文档管理。对于需要多版本API文档的项目，确保每个文档都有唯一的DocumentName是关键所在。