在C# ASP.NET中为Swagger实现Postman式环境变量功能

一、添加环境变量管理界面到Swagger UI #

通过自定义Swagger UI的注入脚本，添加一个环境变量配置区域，让用户可以输入键值对形式的环境变量。

在Program.cs（.NET 6+）或Startup.cs（.NET 5及更早版本）中配置Swagger时，添加自定义JavaScript注入：

builder.Services.AddSwaggerGen();

builder.Services.AddSwaggerUI(options =>
{
    options.InjectJavascript("/swagger-env-vars.js");
});

在项目的wwwroot目录下创建swagger-env-vars.js文件，内容如下：

// 初始化环境变量存储，可预设常用变量
window.envVariables = {
    "baseUrl": "https://localhost:7001",
    "apiKey": "test-key-123"
};

// 生成环境变量配置面板
function addEnvVarPanel() {
    const container = document.querySelector('.swagger-ui .topbar');
    const envPanel = document.createElement('div');
    envPanel.style.marginLeft = '20px';
    envPanel.innerHTML = `
        <div style="display: flex; gap: 10px; align-items: center;">
            <label>环境变量:</label>
            <input type="text" id="envKey" placeholder="变量名" style="padding: 4px; width: 120px;">
            <input type="text" id="envValue" placeholder="变量值" style="padding: 4px; width: 200px;">
            <button onclick="addEnvVar()">添加/修改</button>
        </div>
        <div id="envVarList" style="margin-top: 8px; color: #666; font-size: 12px;"></div>
    `;
    container.appendChild(envPanel);
    renderEnvVarList();
}

// 添加/更新环境变量
function addEnvVar() {
    const key = document.getElementById('envKey').value.trim();
    const value = document.getElementById('envValue').value.trim();
    if (key) {
        window.envVariables[key] = value;
        renderEnvVarList();
        document.getElementById('envKey').value = '';
        document.getElementById('envValue').value = '';
    }
}

// 渲染已添加的环境变量列表
function renderEnvVarList() {
    const listEl = document.getElementById('envVarList');
    listEl.innerHTML = Object.entries(window.envVariables).map(([k, v]) => `${k}: ${v}`).join(' | ');
}

// 拦截Swagger请求，自动替换变量
function interceptSwaggerRequests() {
    const originalFetch = window.fetch;
    window.fetch = function(resource, options) {
        // 替换URL中的{{变量}}
        let url = resource;
        if (typeof url === 'string') {
            url = replaceEnvVariables(url);
        }

        // 替换请求体中的{{变量}}
        if (options?.body) {
            let body = options.body;
            // 处理JSON字符串格式的请求体
            if (typeof body === 'string') {
                body = replaceEnvVariables(body);
                options.body = body;
            }
            // 处理FormData格式的请求体
            else if (body instanceof FormData) {
                for (let [key, value] of body.entries()) {
                    if (typeof value === 'string') {
                        body.set(key, replaceEnvVariables(value));
                    }
                }
            }
        }

        return originalFetch(url, options);
    };
}

// 通用变量替换逻辑
function replaceEnvVariables(str) {
    return str.replace(/{{(\w+)}}/g, (match, key) => {
        return window.envVariables[key] || match;
    });
}

// 页面加载完成后初始化
window.addEventListener('load', () => {
    addEnvVarPanel();
    interceptSwaggerRequests();
});

二、功能测试 #

1. 启动项目打开Swagger UI，顶部会出现环境变量配置区域。
2. 添加变量（比如something，值设为api/v1）。
3. 在API URL中使用{{something}}（例如/{{something}}/users），发送请求时会自动替换为/api/v1/users。
4. 在请求体中使用变量，比如JSON格式：

{
    "apiKey": "{{apiKey}}",
    "baseUrl": "{{baseUrl}}"
}

发送请求时会自动替换为对应的环境变量值。

三、可选进阶优化 #

• 多环境切换：扩展脚本添加环境保存/加载功能，预设开发、测试、生产等环境的变量集合。
• 变量验证：添加输入校验逻辑，避免无效的变量名或值。
• 后端配合：若需要网关或后端层面处理变量，可在请求头中携带环境变量标识，后端再进行替换（一般Swagger UI层面处理已满足日常调试需求）。

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