能否使用SwashBuckle修改Swagger UI对应的HTML页面标题

架构老林

2026-10-2

操作方案

完全可以通过SwashBuckle的内置配置修改Swagger UI页面的标题，不同版本的配置方式如下：

SwashBuckle.AspNetCore 6.x 及以上版本

直接在SwaggerUI的配置项中指定DocumentTitle属性即可，示例代码（.NET 6+ 顶层语句写法）：

var builder = WebApplication.CreateBuilder(args);

// 省略其他服务注册配置
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "用户服务 v1");
        // 这里设置页面标题
        options.DocumentTitle = "用户服务接口文档";
    });
}

app.Run();

SwashBuckle.AspNetCore 5.x 及更低版本

低版本没有内置DocumentTitle配置，需要通过注入自定义头部脚本实现：

在项目中新增一个HTML文件，命名为swagger-custom-head.html，内容如下：

<script>
    // 页面加载完成后替换标题
    window.onload = () => {
        document.title = "支付服务接口文档";
    };
</script>

右键点击该文件，选择「属性」，将「生成操作」设置为「嵌入的资源」
在SwaggerUI配置中引入自定义头部文件：

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "支付服务 v1");
    options.HeadContent = "swagger-custom-head.html";
});

多版本接口动态标题配置

如果你的服务存在多版本接口，可以配置动态标题，跟随当前选中的接口版本自动切换：

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "商品服务 v1");
    options.SwaggerEndpoint("/swagger/v2/swagger.json", "商品服务 v2");
    // 切换版本时自动更新标题
    options.OnComplete(@"() => {
        const currentVersion = document.querySelector('.swagger-ui .select-wrapper span').textContent;
        document.title = currentVersion + ' 接口文档';
    }");
});