.NET Core Swagger/OpenAPI页面多语言支持实现方法问询

一、SwaggerUI界面元素的多语言切换（按钮、提示文字翻译） #

SwaggerUI原生支持通过加载本地化资源文件切换界面语言，按以下步骤配置：

1. 在SwaggerUI中注入自定义脚本
   修改UseSwaggerUI的配置，添加语言切换所需的脚本引用：

app.UseSwagger();
app.UseSwaggerUI(options =>
{
    var path = string.IsNullOrWhiteSpace(options.RoutePrefix) ? "." : "..";
    options.SwaggerEndpoint($"{path}/swagger/v1/swagger.json", "API v1");

    // 注入语言切换逻辑脚本和各语言本地化文件
    options.InjectJavascript("/swagger/ui/language-switch.js");
    options.InjectJavascript("/swagger/ui/translator.js");
    options.InjectJavascript("/swagger/ui/en.js"); // 英语本地化文件
    options.InjectJavascript("/swagger/ui/fr.js"); // 法语本地化文件
    options.InjectJavascript("/swagger/ui/es.js"); // 西班牙语本地化文件
});

2. 准备本地化文件与切换脚本

• 本地化文件：获取对应语言的en.js、fr.js、es.js（包含SwaggerUI界面元素的翻译配置），放到项目wwwroot/swagger/ui目录下。
• language-switch.js：添加语言切换按钮到SwaggerUI头部：

document.addEventListener('DOMContentLoaded', () => {
    const header = document.querySelector('.swagger-ui .topbar');
    const langSwitchGroup = document.createElement('div');
    langSwitchGroup.style.cssText = "margin-right:20px; display:flex; gap:8px;";
    langSwitchGroup.innerHTML = `
        <button onclick="switchLang('en')" style="padding:4px 8px;">English</button>
        <button onclick="switchLang('fr')" style="padding:4px 8px;">Français</button>
        <button onclick="switchLang('es')" style="padding:4px 8px;">Español</button>
    `;
    header.appendChild(langSwitchGroup);
});

function switchLang(lang) {
    window.swaggerTranslator?.translate(lang);
}

• translator.js：管理本地化切换逻辑：

window.swaggerTranslator = {
    currentLang: 'en',
    translations: {},
    init() {
        // 初始化各语言翻译配置
        this.translations['en'] = window.swaggerUIBundle.translations.en;
        this.translations['fr'] = window.swaggerUIBundle.translations.fr;
        this.translations['es'] = window.swaggerUIBundle.translations.es;
    },
    translate(lang) {
        if (!this.translations[lang]) return;
        this.currentLang = lang;
        // 更新SwaggerUI的翻译配置
        window.ui?.updateTranslations(this.translations[lang]);
    }
};

document.addEventListener('DOMContentLoaded', () => {
    window.swaggerTranslator.init();
});

二、API文档内容的多语言（接口、参数描述翻译） #

如果需要接口名称、参数说明等文档内容支持多语言，需生成对应语言的Swagger文档：

1. 配置多语言Swagger文档生成
   修改AddSwaggerGen，为每种语言创建独立的文档：

services.AddSwaggerGen(options =>
{
    // 英语文档
    options.SwaggerDoc("v1-en", new OpenApiInfo
    {
        Version = "v1",
        Title = "API v1 (English)",
        Description = "English API Documentation"
    });

    // 法语文档
    options.SwaggerDoc("v1-fr", new OpenApiInfo
    {
        Version = "v1",
        Title = "API v1 (Français)",
        Description = "Documentation de l'API en français"
    });

    // 西班牙语文档
    options.SwaggerDoc("v1-es", new OpenApiInfo
    {
        Version = "v1",
        Title = "API v1 (Español)",
        Description = "Documentación de la API en español"
    });

    // 加载对应语言的XML注释文件（需提前为每种语言生成注释）
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "YourApi.en.xml"));
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "YourApi.fr.xml"));
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "YourApi.es.xml"));
});

2. 在SwaggerUI中加载多语言文档
   更新UseSwaggerUI，添加多个语言的文档端点：

app.UseSwaggerUI(options =>
{
    var path = string.IsNullOrWhiteSpace(options.RoutePrefix) ? "." : "..";
    options.SwaggerEndpoint($"{path}/swagger/v1-en/swagger.json", "API v1 (English)");
    options.SwaggerEndpoint($"{path}/swagger/v1-fr/swagger.json", "API v1 (Français)");
    options.SwaggerEndpoint($"{path}/swagger/v1-es/swagger.json", "API v1 (Español)");

    // 保留界面语言切换的脚本注入
    options.InjectJavascript("/swagger/ui/language-switch.js");
    options.InjectJavascript("/swagger/ui/translator.js");
    options.InjectJavascript("/swagger/ui/en.js");
    options.InjectJavascript("/swagger/ui/fr.js");
    options.InjectJavascript("/swagger/ui/es.js");
});

注意事项 #

• 确保项目已启用静态文件服务（app.UseStaticFiles();，默认.NET Core项目已配置），否则本地化脚本无法被访问。
• 若仅需要SwaggerUI界面的多语言，只需实现第一部分即可；若需要文档内容的多语言，再完成第二部分配置。

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