ASP.NET Core 3.1中如何为Swagger各版本插入静态HTML内容？

步骤1：准备版本对应的静态HTML文件 #

在项目的wwwroot目录下创建子目录（比如swagger-descriptions），为每个API版本单独创建HTML文件，例如：

• wwwroot/swagger-descriptions/v1-description.html（对应v1版本的自定义内容）
• wwwroot/swagger-descriptions/v2-description.html（对应v2版本的自定义内容）

步骤2：在Swagger文档配置中添加版本HTML路径扩展 #

修改Startup.cs中AddSwaggerGen的配置，为每个版本的Swagger文档添加自定义扩展属性，存储对应HTML文件的路径：

services.AddSwaggerGen(c =>
{
    // 配置v1版本文档
    var v1Info = new OpenApiInfo
    {
        Title = "My API V1",
        Version = "v1",
        Description = "基础API版本"
    };
    c.SwaggerDoc("v1", v1Info);
    // 添加自定义扩展，标记对应HTML文件路径
    c.SwaggerDoc("v1").Extensions.Add("X-DescriptionHtmlPath", "/swagger-descriptions/v1-description.html");

    // 配置v2版本文档
    var v2Info = new OpenApiInfo
    {
        Title = "My API V2",
        Version = "v2",
        Description = "增强API版本"
    };
    c.SwaggerDoc("v2", v2Info);
    c.SwaggerDoc("v2").Extensions.Add("X-DescriptionHtmlPath", "/swagger-descriptions/v2-description.html");

    // 保留你已有的DocInclusionPredicate配置
    c.DocInclusionPredicate((docName, apiDesc) =>
    {
        if (!apiDesc.TryGetMethodInfo(out MethodInfo methodInfo)) return false;
        var versions = methodInfo.DeclaringType.GetCustomAttributes(true)
            .OfType<ApiVersionAttribute>()
            .SelectMany(attr => attr.Versions);
        return versions.Any(v => $"v{v.ToString()}" == docName);
    });
});

步骤3：注入自定义脚本处理版本切换与HTML加载 #

在Startup.cs的UseSwaggerUI配置中，注入自定义JavaScript脚本，用于监听Swagger版本切换事件并加载对应HTML：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "My API V2");

    // 注入自定义脚本文件
    c.InjectJavascript("/swagger-custom-scripts/load-version-description.js");
});

步骤4：编写自定义JavaScript脚本 #

在wwwroot下创建swagger-custom-scripts/load-version-description.js文件，实现HTML加载与插入逻辑：

// 加载版本特异性HTML内容的核心函数
function loadVersionSpecificDescription() {
    // 获取当前选中的Swagger文档信息
    const currentDoc = window.ui.getState().selectedDoc;
    if (!currentDoc) return;

    // 从文档扩展属性中获取HTML文件路径
    const htmlPath = currentDoc.info.extensions["X-DescriptionHtmlPath"];
    if (!htmlPath) return;

    // 定位到description容器
    const descriptionElement = document.querySelector('.information-container .description');
    if (!descriptionElement) return;

    // 移除之前已插入的自定义内容
    const existingCustomContent = descriptionElement.nextElementSibling;
    if (existingCustomContent?.classList.contains('custom-version-desc')) {
        existingCustomContent.remove();
    }

    // 加载并插入新的HTML内容
    fetch(htmlPath)
        .then(res => res.text())
        .then(html => {
            const customDiv = document.createElement('div');
            customDiv.className = 'custom-version-desc';
            customDiv.innerHTML = html;
            descriptionElement.parentNode.insertBefore(customDiv, descriptionElement.nextSibling);
        })
        .catch(err => console.error('加载版本描述失败:', err));
}

// 页面初始化时加载一次
document.addEventListener('DOMContentLoaded', loadVersionSpecificDescription);

// 监听Swagger文档切换事件，切换版本时重新加载
window.ui.onDocChange = loadVersionSpecificDescription;

注意事项 #

1. 确保已启用静态文件中间件（app.UseStaticFiles();），否则无法访问wwwroot下的HTML和脚本文件
2. 若使用的Swashbuckle.AspNetCore版本较低，可能需要调整脚本中获取当前文档的方式（比如window.swaggerUi而非window.ui）
3. 可根据需求自定义custom-version-desc类的CSS样式，优化显示效果

内容的提问来源于stack exchange，提问作者Stephen Cossgrove