.NET API控制器在Swagger中返回双重响应问题排查

问题描述 #

调用外部API的服务可正常返回数据，但API控制器在Swagger中存在异常：未点击“Try to execute”时，Swagger展示空值的模型响应；点击“Execute”后，会显示正确响应，但该响应下方仍保留之前的空值响应。

现有代码 #

服务代码 #

public async Task<EmployeeDetails> EmployeeDetails(int employeId)
{
    var client = new HttpClient();
    client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "bearertokenvalue");
    var response = await client.GetAsync("http://someapi/employee/{employeId}");
    var resultData = response.Content.ReadAsStringAsync();
    EmployeeDetails employe = JsonConvert.DeserializeObject<EmployeeDetails>(resultData.Result);
    return employe;
}

API控制器代码 #

[HttpGet]
public async Task<EmployeeDetails> Run()
{
    var response = await _employeService.EmployeeDetails(2);
    return response;
}

问题定位 #

1. Swagger元数据推断缺失：控制器直接返回Task<EmployeeDetails>，ASP.NET Core无法为Swagger提供足够的响应元数据，导致初始展示空模型。
2. 异步操作处理错误：ReadAsStringAsync()未使用await，直接调用.Result可能引发异步状态异常，间接影响Swagger的元数据生成逻辑。
3. URL参数未实际替换：GetAsync中的URL硬写了{employeId}，未替换为传入的参数值，属于潜在逻辑错误。
4. HttpClient未复用：每次创建新HttpClient实例会耗尽连接池，影响服务稳定性。

修复方案 #

1. 修复服务代码的异步逻辑与资源复用 #

使用IHttpClientFactory注入HttpClient，正确处理异步操作和URL参数：

// 服务类构造函数注入IHttpClientFactory
private readonly IHttpClientFactory _httpClientFactory;

public YourEmployeeService(IHttpClientFactory httpClientFactory)
{
    _httpClientFactory = httpClientFactory;
}

public async Task<EmployeeDetails> EmployeeDetails(int employeId)
{
    var client = _httpClientFactory.CreateClient();
    client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "bearertokenvalue");
    // 字符串插值替换URL参数
    var response = await client.GetAsync($"http://someapi/employee/{employeId}");
    // 确保请求成功，避免无效响应反序列化失败
    response.EnsureSuccessStatusCode();
    // 异步读取响应内容
    var resultData = await response.Content.ReadAsStringAsync();
    var employe = JsonConvert.DeserializeObject<EmployeeDetails>(resultData);
    return employe;
}

2. 优化控制器返回类型与Swagger元数据 #

使用ActionResult<T>作为返回类型，并添加特性明确告知Swagger响应模型：

[HttpGet]
// 明确指定200状态码对应的响应模型
[ProducesResponseType(typeof(EmployeeDetails), StatusCodes.Status200OK)]
// 可选：添加错误状态码的响应说明
[ProducesResponseType(StatusCodes.Status500InternalServerError)]
public async Task<ActionResult<EmployeeDetails>> Run()
{
    var response = await _employeService.EmployeeDetails(2);
    return Ok(response);
}

3. 可选：增强模型展示细节 #

为EmployeeDetails类添加XML注释，在项目中启用XML文档文件并配置Swagger读取该文件，可让Swagger展示更详细的模型字段说明。

验证步骤 #

1. 启动项目并访问Swagger页面
2. 查看目标接口的响应模型，此时应正常显示EmployeeDetails的结构，而非空模型
3. 点击“Execute”执行请求，确认正确响应展示且无残留空模型

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