使用Swashbuckle注解后Swagger UI响应体显示字符串而非JSON对象的问题

出现这个问题的核心原因是Swashbuckle注解覆盖了默认的响应类型推断，导致Swagger UI将响应识别为JSON字符串而非强类型对象。以下是具体的解决步骤：

1. 检查API接口的返回类型与Swagger注解 #

• 确保你的API方法直接返回强类型实体对象（而非string或Task<string>），不要手动将对象序列化为JSON字符串后返回。
• 如果使用了[SwaggerResponse]注解，必须正确指定响应类型为你的实体类，而非string。示例：

  [HttpGet]
  [SwaggerResponse(StatusCodes.Status200OK, Type = typeof(YourModel))]
  public IActionResult Get()
  {
      var model = new YourModel 
      { 
          Id = Guid.NewGuid(), 
          Name = "Test",
          HexColor = "121213",
          IsActive = true,
          PlanInstanceId = Guid.NewGuid()
      };
      return Ok(model); // 直接返回对象，而非序列化后的字符串
  }
  

2. 对齐Swagger与项目的JSON序列化配置 #

在AddSwaggerGen中同步项目的JSON序列化设置，避免注解包导致的序列化规则差异：

builder.Services.AddSwaggerGen(options =>
{
    options.EnableAnnotations();
    // 同步项目的JSON序列化配置
    options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
    options.JsonSerializerOptions.DictionaryKeyPolicy = JsonNamingPolicy.CamelCase;
    options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
    options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles;
});

3. 排查全局序列化拦截逻辑 #

如果项目中存在全局中间件、过滤器或自定义格式化器，检查是否存在将响应对象强制序列化为JSON字符串的逻辑。这类逻辑会让Swashbuckle误判响应类型为string，需调整为直接返回强类型对象，由ASP.NET Core自动完成序列化。

完成以上调整后，重启项目即可看到Swagger UI的响应体显示为格式化的JSON对象。

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