ASP.NET Core OpenAPI 整数类型序列化的行为变更解析

在ASP.NET Core项目中，当使用OpenAPI规范描述API时，开发人员可能会注意到一个关于整数类型序列化的细微但重要的行为变化。这个变化主要影响OpenAPI文档中整数属性的类型定义方式。

行为变更现象

在较新版本的ASP.NET Core中，整数类型属性在OpenAPI文档中的定义方式发生了变化。以"age"属性为例：

旧版本中，整数类型会简单地定义为：

{
  "type": "integer",
  "format": "int32"
}

而在新版本中，同样的属性可能会被描述为：

{
  "pattern": "^-?(?:0|[1-9]\\d*)$",
  "type": ["integer", "string"],
  "format": "int32"
}

或者在OpenAPI 3.0规范下表现为：

{
  "pattern": "^-?(?:0|[1-9]\\d*)$",
  "format": "int64"
}

变更原因分析

这一行为变化源于ASP.NET Core默认JSON序列化配置的调整。具体来说，这是由于JsonSerializerOptions中的NumberHandling属性默认设置为AllowReadingFromString导致的。

当NumberHandling设置为AllowReadingFromString时，JSON序列化器允许数字既可以被序列化为数值类型，也可以被序列化为字符串类型。这种灵活性反映在OpenAPI文档中，就表现为类型定义的多样性。

解决方案

如果开发者希望保持传统的严格整数类型定义（仅type: integer），可以通过以下方式配置：

var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.NumberHandling = JsonNumberHandling.Strict;
});

这一配置会强制JSON序列化器只接受严格的数值类型，从而在OpenAPI文档中生成更简洁的类型定义。

技术背景

这一变更实际上更准确地反映了.NET序列化器的实际行为。在允许从字符串读取数字的配置下，API确实可以接受两种形式的输入（字符串或数字），因此OpenAPI文档中同时列出两种类型是更符合实际情况的做法。

对于需要严格类型检查的API，显式设置Strict模式是推荐的做法。这不仅会影响OpenAPI文档的生成，也会确保API端点只接受严格符合预期的数据类型。

最佳实践建议

1. 对于新项目，建议根据实际需求明确设置NumberHandling属性
2. 对于已有项目升级时，检查是否依赖了从字符串解析数字的功能
3. 在团队协作中，应在项目文档中明确记录这方面的配置选择
4. 如果API客户端需要处理多种数字格式，保留默认配置可能更合适

这一变化虽然细微，但对于API的强类型化和文档准确性有重要意义，值得开发者在升级时注意。