.NET Core 6中如何基于JSON Schema配置ResponseType？

1. 自动生成强类型类（最推荐） #

针对现有使用匿名类型返回的API，通过工具批量生成对应实体类：

• 抓取单个API的实际JSON返回结果，用VS自带的「粘贴JSON作为类」功能一键生成强类型类
• 批量处理时，可编写控制台程序遍历所有API的返回示例JSON，自动生成对应的C#/VB类文件
• 将原代码中的New With { ... }替换为生成的类实例，再给API添加[ProducesResponseType(typeof(生成的类), StatusCodes.Status200OK)]属性
  完成后Swagger可直接识别响应类型，前端工具（如NSwag、OpenAPI Generator）能基于Swagger自动生成代码

2. 直接在Swagger中配置自定义Schema（无需修改业务代码） #

若不想改动现有API的返回逻辑，可在Swagger配置中给指定API绑定JSON Schema：

• 通过Swashbuckle的IOperationFilter扩展，批量注入预定义的JSON Schema：

  public class CustomSchemaInjectFilter : IOperationFilter
  {
      public void Apply(OpenApiOperation operation, OperationFilterContext context)
      {
          // 根据API路由或特性匹配对应的JSON Schema文件路径
          var schemaFilePath = GetMatchedSchemaPath(context.ApiDescription);
          if (!string.IsNullOrEmpty(schemaFilePath))
          {
              var schemaJson = File.ReadAllText(schemaFilePath);
              var targetSchema = JsonSerializer.Deserialize<OpenApiSchema>(schemaJson);
              operation.Responses["200"].Content["application/json"].Schema = targetSchema;
          }
      }
  
      private string GetMatchedSchemaPath(ApiDescription apiDesc)
      {
          // 自定义匹配逻辑，比如根据路由映射到对应的Schema文件
          return $"Schemas/{apiDesc.Route.RouteTemplate.Replace("/", "_")}.json";
      }
  }
  

• 在项目启动配置中注册该过滤器：

  builder.Services.AddSwaggerGen(options =>
  {
      options.OperationFilter<CustomSchemaInjectFilter>();
  });
  

此方式仅需维护JSON Schema文件，无需修改原有API业务代码

3. 基于XML注释的示例推导Schema #

若已有API返回示例，可通过Swagger的XML注释支持自动推导Schema：

• 在API的XML注释中添加<example>标签，填入对应的JSON返回示例
• 启用Swagger的XML注释解析功能，开启示例自动推导，Swagger会根据示例生成对应的响应Schema
  该方法适合结构简单的API，复杂结构需保证示例的准确性

4. 动态类型结合Swagger注解 #

若不愿生成强类型类，可使用dynamic配合Swagger注解指定Schema：

• 给API添加[SwaggerResponse(StatusCodes.Status200OK, Type = typeof(object))]，并在XML注释中附上JSON Schema内容
• 或通过[SwaggerSchemaFilter]动态为返回类型绑定预定义的Schema，本质和第二种方案逻辑一致

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