粘贴由 class、record 或 struct 构成的 C# 模型,就能得到遵循 System.Text.Json 和 Newtonsoft.Json 规则的示例 JSON 文档。可以在 ASP.NET Core 默认使用的 camelCase 命名策略与按原样书写的属性名之间选择;用 [JsonPropertyName] 或 [JsonProperty] 设置的名称始终优先。
可以根据 Web API 的请求/响应模型给前端或外部合作方提供示例、填写 Swagger(Swashbuckle)示例,或为 HttpClient 集成测试准备请求体。
using、namespace、构造函数和方法都可以保留。命名策略:标准的 Web API 项目选 camelCase(ASP.NET Core 默认);如果设置了 PropertyNamingPolicy = null 或依赖 Newtonsoft 的默认设置,则选 保持属性名不变。根类型 设为 自动 时,第一个没有被其他模型引用的类型会成为根;需要时可从列表中更改。.http 文件或 xUnit 请求体中。选项的选择会保存在 URL 中。public class InventoryItem
{
public Guid Id { get; set; }
public string SKU { get; set; } = "";
[JsonPropertyName("stock_qty")]
public int StockQuantity { get; set; }
public StockState State { get; set; } = StockState.InStock;
public DateTimeOffset UpdatedAt { get; set; }
public List<string> Barcodes { get; set; } = new();
[JsonIgnore]
public string WarehouseNote { get; set; } = "";
private int _version;
}
public enum StockState { InStock, LowStock, OutOfStock }{
"id": "00000000-0000-0000-0000-000000000000",
"sku": "",
"stock_qty": 0,
"state": 0,
"updatedAt": "1970-01-01T00:00:00+00:00",
"barcodes": [
""
]
}在 camelCase 策略下,SKU 这样的全大写名称变成 sku,与 System.Text.Json 的 JsonNamingPolicy.CamelCase 一致;而 [JsonPropertyName("stock_qty")] 无论策略如何都保持其名称。WarehouseNote([JsonIgnore])和 private 字段 _version 被排除。enum State 没有字符串转换器,所以显示 0,即其初始值 StockState.InStock 的数值。
[JsonPropertyName]、Newtonsoft 的 [JsonProperty] 以及 [DataMember(Name = ...)]。public 属性和字段,以及标记了 [JsonInclude] 的非 public 成员。排除 static、const、[JsonIgnore] 和 [IgnoreDataMember];Condition = WhenWritingNull 这样的条件忽略会被保留。record Customer(long Id, string Name))和 [property: JsonPropertyName(...)] 目标。=> ...)会被包含,与 System.Text.Json 的序列化行为一致。= 10 这样的显式值)。如果 enum 或属性上有 [JsonConverter(typeof(JsonStringEnumConverter))](或 Newtonsoft 的 StringEnumConverter),或者成员上有 [JsonStringEnumMemberName] / [EnumMember(Value = ...)],则改用名称字符串。DateTime → 1970-01-01T00:00:00,DateTimeOffset → 1970-01-01T00:00:00+00:00,DateOnly → 1970-01-01,TimeOnly/TimeSpan → 00:00:00,Guid → 全零 GUID。int?/Nullable<T> 使用内部类型,List<T>/IEnumerable<T>/数组得到一个元素,Dictionary<int, V> 使用 "0" 作为 key,object、JsonElement 和 JObject 变成 null。= 1.5、= "KRW")会用作示例值。混用 [JsonPropertyName] 和默认命名的 DTO,很容易让人误读 Swagger UI 自动生成的示例。把这里的输出用在 ISchemaFilter 或 XML <example> 注释中,文档和响应就会使用相同的 key。
对同一个模型来回切换 命名策略,预览迁移后 key 的大小写会如何变化。
当客户端和服务器各自保留一份模型副本时,分别从两边生成 JSON 并对比,可以快速发现 key 名不一致的地方。
Program.cs 中通过 AddJsonOptions 全局注册的 JsonStringEnumConverter 在模型代码中看不到,所以 enum 仍会输出为数字。要看到名称,请在粘贴前给 enum 声明加上 [JsonConverter(typeof(JsonStringEnumConverter))]。string? 这样的可空引用类型会得到按类型生成的示例,而不是 null。[JsonConverter] 特性、JsonSerializerOptions 中的 DefaultIgnoreCondition,以及 snake_case 策略(JsonNamingPolicy.SnakeCaseLower)。[JsonPolymorphic]/[JsonDerivedType] 实现的多态;只会生成声明的基类型。命名策略 的各个选项分别在什么时候用?ASP.NET Core Web API 使用 JsonSerializerDefaults.Web,即 camelCase。不带选项调用 JsonSerializer.Serialize 的控制台应用,或使用 Newtonsoft.Json 默认设置时,属性名保持不变,这时请选择 保持属性名不变。
public string FullName => ... 这样的计算属性?System.Text.Json 和 Newtonsoft.Json 都会序列化带 getter 的 public 属性,所以计算属性也会出现在响应中。如果不想输出它们,请加上 [JsonIgnore]。
[JsonPropertyName] 在运行时没有重命名 key。不指定目标时,编译器只把该特性应用到构造函数参数上。本工具两种写法都能识别,但要可靠地重命名序列化后的属性,请写成 [property: JsonPropertyName("...")]。
DateTime 值没有 Z?DateTimeKind.Unspecified 的 DateTime 序列化时不带偏移。如果需要显式的 UTC 偏移,DateTimeOffset 会输出 +00:00 形式。