FastEndpoints项目中的OpenAPI服务器URL与路由前缀配置技巧

在使用FastEndpoints框架开发API时，合理配置OpenAPI文档中的服务器URL和路由前缀是API设计的重要环节。本文将深入探讨如何正确设置这些配置项，避免常见错误。

配置问题分析

开发者在尝试配置OpenAPI文档时，经常遇到服务器URL和路由路径重复的问题。典型表现为：

• 服务器URL设置为https://localhost:5001/api/v1
• 路由路径也包含/api/v1前缀
• 最终生成的OpenAPI文档中出现重复路径

正确配置方法

1. 基础配置

首先需要确保基本的Swagger配置正确，避免使用不必要的方法调用：

services.AddFastEndpoints();
services.SwaggerDocument(o =>
{
    o.MaxEndpointVersion = 1;
    o.ShortSchemaNames = true;
    o.DocumentSettings = d =>
    {
        d.Title = "API文档标题";
        d.DocumentName = "v1";
    };
});

2. 路由前缀配置

在应用构建阶段，通过MapFastEndpoints方法配置路由前缀和版本控制：

app.UseEndpoints(endpoints =>
{
    endpoints.MapFastEndpoints(o =>
    {
        o.Versioning.DefaultVersion = 1;
        o.Versioning.Prefix = "v";
        o.Versioning.PrependToRoute = true;
        o.Endpoints.RoutePrefix = "api";
    });
});

3. OpenAPI服务器URL定制

如果需要自定义OpenAPI文档中的服务器URL，可以在Swagger配置中处理：

services.SwaggerDocument(o =>
{
    o.DocumentSettings = d =>
    {
        d.PostProcess = p =>
        {
            p.Servers.Clear();
            p.Servers.Add(new OpenApiServer 
            { 
                Url = $"https://{Configurations.Settings.ApiHostName}" 
            });
        };
    };
});

高级技巧

路径重写

对于需要特殊处理的路径，可以使用路径重写技术：

o.DocumentSettings = d =>
{
    d.Paths = (paths) =>
    {
        var modifiedPaths = new OpenApiPaths();
        foreach (var path in paths)
        {
            // 移除路径中的/api/v1前缀
            var newPath = path.Key.Replace("/api/v1", "");
            modifiedPaths.Add(newPath, path.Value);
        }
        return modifiedPaths;
    };
};

常见错误避免

1. 避免重复调用：不要同时使用AddEndpointsApiExplorer()和UseOpenApi()，FastEndpoints已经内置了这些功能

2. 版本控制一致性：确保路由配置和Swagger文档中的版本号一致

3. 路径处理顺序：路径重写应该在所有其他处理完成后进行

通过以上配置，开发者可以灵活控制OpenAPI文档中的服务器URL和路径显示，同时保持实际路由结构的清晰和一致。这种配置方式既满足了API文档的可读性需求，又保持了实际路由的简洁性。