Dán các model C# viết bằng class, record hoặc struct để nhận một tài liệu JSON mẫu theo quy tắc của System.Text.Json và Newtonsoft.Json. Bạn chọn giữa chính sách đặt tên camelCase mà ASP.NET Core dùng mặc định và giữ nguyên tên thuộc tính như đã viết; tên được đặt bằng [JsonPropertyName] hoặc [JsonProperty] luôn được ưu tiên.
Dùng nó để đưa mẫu cho frontend hay đối tác bên ngoài từ model request/response của Web API, để điền example cho Swagger (Swashbuckle), hoặc để chuẩn bị body cho integration test với HttpClient.
using, namespace, constructor và method có thể để nguyên.Quy tắc đặt tên: camelCase (mặc định của ASP.NET Core) cho dự án Web API thông thường, hoặc Giữ nguyên tên thuộc tính nếu bạn đặt PropertyNamingPolicy = null hay dựa vào mặc định của Newtonsoft.Kiểu gốc để Tự động, kiểu đầu tiên không được model nào khác tham chiếu sẽ thành gốc; đổi trong danh sách nếu cần..http hoặc body request trong xUnit. Các lựa chọn option được lưu trong 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": [
""
]
}Với chính sách camelCase, tên viết hoa toàn bộ như SKU thành sku, khớp với JsonNamingPolicy.CamelCase của System.Text.Json, còn [JsonPropertyName("stock_qty")] giữ tên của nó bất kể chính sách. WarehouseNote ([JsonIgnore]) và field private _version bị loại ra. Enum State không có string converter nên hiện 0, giá trị số của initializer StockState.InStock.
[JsonPropertyName] của System.Text.Json, [JsonProperty] của Newtonsoft, và [DataMember(Name = ...)].public, cùng các member không public được đánh dấu [JsonInclude]. static, const, [JsonIgnore] và [IgnoreDataMember] bị loại; ignore có điều kiện như Condition = WhenWritingNull vẫn được giữ.record Customer(long Id, string Name)) và target [property: JsonPropertyName(...)].=> ...) được đưa vào, giống như System.Text.Json sẽ serialize chúng.= 10). Khi có [JsonConverter(typeof(JsonStringEnumConverter))] (hoặc StringEnumConverter của Newtonsoft) trên enum hay property, hoặc [JsonStringEnumMemberName] / [EnumMember(Value = ...)] trên member, chuỗi tên sẽ được dùng thay thế.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 toàn số 0.int?/Nullable<T> dùng kiểu bên trong, List<T>/IEnumerable<T>/mảng có một phần tử, Dictionary<int, V> dùng key "0", còn object, JsonElement và JObject thành null.= 1.5, = "KRW") được dùng làm giá trị mẫu.DTO trộn [JsonPropertyName] với cách đặt tên mặc định khiến example tự sinh của Swagger UI dễ bị hiểu sai. Dùng output này trong ISchemaFilter hoặc comment XML <example> để tài liệu và response dùng chung một bộ key.
Đổi qua lại Quy tắc đặt tên trên cùng một model để xem trước cách viết hoa/thường của key thay đổi thế nào sau khi migrate.
Khi client và server giữ hai bản model riêng, hãy tạo JSON từ mỗi bên rồi so sánh để nhanh chóng phát hiện tên key lệch nhau.
JsonStringEnumConverter đăng ký toàn cục bằng AddJsonOptions trong Program.cs không hiện ra trong code model, nên enum vẫn ra dạng số. Muốn thấy tên, hãy thêm [JsonConverter(typeof(JsonStringEnumConverter))] vào khai báo enum trước khi dán.string? nhận giá trị mẫu theo kiểu, không phải null.[JsonConverter] tùy biến khác ngoài enum string converter, DefaultIgnoreCondition trong JsonSerializerOptions, và chính sách snake_case (JsonNamingPolicy.SnakeCaseLower) không được áp dụng.[JsonPolymorphic]/[JsonDerivedType] không được hỗ trợ; chỉ kiểu cơ sở đã khai báo được tạo ra.Quy tắc đặt tên?ASP.NET Core Web API dùng JsonSerializerDefaults.Web, tức camelCase. Một console app gọi JsonSerializer.Serialize không kèm option, hoặc thiết lập mặc định của Newtonsoft.Json, giữ nguyên tên thuộc tính, nên ở đó hãy chọn Giữ nguyên tên thuộc tính.
public string FullName => ... lại xuất hiện?Cả System.Text.Json và Newtonsoft.Json đều serialize property public có getter, nên computed property cũng có mặt trong response. Thêm [JsonIgnore] nếu bạn không muốn xuất chúng ra.
[JsonPropertyName] trên tham số positional của record không đổi tên key lúc runtime.Khi không có target, compiler chỉ áp attribute cho tham số constructor. Công cụ này nhận ra cả hai dạng, nhưng để đổi tên property khi serialize một cách chắc chắn, hãy viết [property: JsonPropertyName("...")].
DateTime không có Z?DateTime với DateTimeKind.Unspecified được serialize không kèm offset. Nếu cần offset UTC tường minh, DateTimeOffset cho ra dạng +00:00.