如何让OpenApi-Generator生成可空的DateTimeOffset类型？

问题根本原因 #

你当前的配置不符合OpenAPI规范要求，生成器无法识别你自定义的type: "DateTimeOffset"值，导致类型映射和nullable配置都没有生效。OpenAPI规范只允许type字段使用内置原始类型（string/number/integer/boolean/array/object），自定义的类型值会被生成器直接忽略。

修正步骤 #

1. 调整SchemaFilter逻辑 #

修改Filter严格遵循OpenAPI规范，用format字段区分两种日期类型，type统一使用内置的string类型：

public class FixDateTimeOffsetTypeSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema model, SchemaFilterContext context)
    {
        // 处理可空DateTimeOffset
        if (context.Type == typeof(DateTimeOffset?))
        {
            model.Type = "string";
            model.Format = "date-time-offset";
            model.Nullable = true;
            // 如果输出的是Swagger 2.0而非OpenAPI 3.x，额外加扩展字段：
            // model.Extensions.Add("x-nullable", true);
        }
        // 处理非可空DateTimeOffset
        else if (context.Type == typeof(DateTimeOffset))
        {
            model.Type = "string";
            model.Format = "date-time-offset";
            model.Nullable = false;
        }
        // 处理可空DateTime
        else if (context.Type == typeof(DateTime?))
        {
            model.Type = "string";
            model.Format = "date-time";
            model.Nullable = true;
            // 如果输出的是Swagger 2.0而非OpenAPI 3.x，额外加扩展字段：
            // model.Extensions.Add("x-nullable", true);
        }
        // 处理非可空DateTime
        else if (context.Type == typeof(DateTime))
        {
            model.Type = "string";
            model.Format = "date-time";
            model.Nullable = false;
        }
    }
}

调整后输出的OpenAPI参数结构应该符合如下规范：

{
  "name": "startDatetime",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time-offset",
    "nullable": true
  }
}

2. 配置OpenAPI Generator类型映射 #

生成客户端时需要添加自定义格式到C#类型的映射规则，同时开启可空类型支持，以C# .NET Core客户端生成为例，生成参数需要加入以下配置：

• 类型映射：--type-mappings "date-time-offset=DateTimeOffset,date-time=DateTime"
• 声明可空类型：--nullable-types "DateTimeOffset,DateTime"
• 开启C#可空引用类型生成：--additional-properties generateNullableReferenceTypes=true

完整生成命令示例：

openapi-generator-cli generate -i ./your-openapi-schema.json -g csharp-netcore --type-mappings "date-time-offset=DateTimeOffset,date-time=DateTime" --nullable-types "DateTimeOffset,DateTime" --additional-properties generateNullableReferenceTypes=true

以上修改完成后，生成的客户端代码就会自动区分DateTime?、DateTime、DateTimeOffset?、DateTimeOffset四种类型，严格匹配服务端定义。

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