FastEndpoints项目中自定义Swagger URL前缀的配置方法

在FastEndpoints项目中，开发者经常需要为Swagger UI和API文档配置自定义的URL前缀，以满足特定的部署需求或组织架构要求。本文将详细介绍如何通过配置实现这一功能。

为什么需要自定义Swagger URL前缀

在实际项目部署中，我们可能需要：

1. 将Swagger UI部署在特定前缀路径下，与其他应用区分
2. 符合企业内部API网关的路由规则
3. 实现多版本API文档共存
4. 满足安全策略要求，将文档访问路径隔离

完整配置方案

FastEndpoints提供了灵活的配置方式，可以同时修改Swagger UI和API文档的访问路径：

app.UseSwaggerGen(
    s =>
    {
        // 配置Swagger JSON文件的访问路径
        s.Path = "/PREFIX/swagger/{documentName}/swagger.json";

        // 自定义API端点服务器基础路径
        s.PostProcess = (document, request) =>
        {
            document.Servers.Clear();
            document.Servers.Add(
                new()
                {
                    Url = $"{request.Scheme}://{request.Host}/PREFIX"
                });
        };
    },
    ui =>
    {
        // 配置Swagger UI的访问路径
        ui.Path = "/PREFIX/swagger";

        // 配置Swagger UI查找JSON文件的路径
        ui.DocumentPath = "/PREFIX/swagger/{documentName}/swagger.json";
    });

配置项详解

1. Swagger JSON配置部分：

   • Path：指定Swagger生成的JSON描述文件的访问路径
   • PostProcess：用于动态修改生成的OpenAPI文档，这里我们重写了服务器URL

2. Swagger UI配置部分：

   • Path：设置Swagger UI的根访问路径
   • DocumentPath：告诉Swagger UI从何处加载API描述文件

实际应用示例

假设我们需要将API文档部署在/api-docs前缀下：

app.UseSwaggerGen(
    s =>
    {
        s.Path = "/api-docs/swagger/{documentName}/swagger.json";
        s.PostProcess = (document, request) =>
        {
            document.Servers.Clear();
            document.Servers.Add(new() { Url = $"{request.Scheme}://{request.Host}/api-docs" });
        };
    },
    ui =>
    {
        ui.Path = "/api-docs/swagger";
        ui.DocumentPath = "/api-docs/swagger/{documentName}/swagger.json";
    });

注意事项

1. 确保所有路径配置中的前缀保持一致
2. 如果使用网络中间件，可能需要额外配置路由规则
3. 在生产环境中，建议限制Swagger UI的访问权限
4. 路径修改后，相关的书签和文档链接也需要相应更新

通过以上配置，开发者可以灵活地将FastEndpoints项目的API文档部署在任何需要的路径前缀下，满足各种复杂的部署场景需求。