แปลงคลาส C# เป็น JSON!

วางโค้ด C# (class·record) แล้วรับ JSON ตัวอย่าง! รองรับ System.Text.Json [JsonPropertyName], Newtonsoft.Json [JsonProperty] เหมาะสำหรับเอกสาร API และ request body สำหรับทดสอบ (mock request body)
C#
ผลลัพธ์
 

แปลงคลาส C# เป็น JSON!

วางโมเดล C# ที่เขียนด้วย class, record หรือ struct แล้วจะได้ตัวอย่าง JSON ตามกฎของ System.Text.Json และ Newtonsoft.Json เลือกได้ระหว่างนโยบายตั้งชื่อแบบ camelCase ซึ่งเป็นค่าเริ่มต้นของ ASP.NET Core กับการใช้ชื่อพร็อพเพอร์ตีตามที่เขียนไว้ ส่วนชื่อที่กำหนดด้วย [JsonPropertyName] หรือ [JsonProperty] จะมีผลเหนือกว่าเสมอ

ใช้เพื่อส่งตัวอย่างจากโมเดล request/response ของ Web API ให้ทีม frontend หรือพาร์ตเนอร์ภายนอก ใช้เติมตัวอย่างใน Swagger (Swashbuckle) หรือเตรียม body สำหรับ integration test ที่ใช้ HttpClient

วิธีใช้

  1. วางซอร์สของโมเดล ไม่ต้องลบ using, namespace, constructor หรือเมธอดออก
  2. เลือก นโยบายการตั้งชื่อ: ใช้ camelCase (ค่าเริ่มต้นของ ASP.NET Core) สำหรับโปรเจกต์ Web API ทั่วไป หรือ ใช้ชื่อพร็อพเพอร์ตีตามเดิม ถ้าคุณตั้ง PropertyNamingPolicy = null หรือใช้ค่าเริ่มต้นของ Newtonsoft
  3. เมื่อ ชนิดราก เป็น อัตโนมัติ ไทป์แรกที่ไม่มีโมเดลอื่นอ้างถึงจะเป็นราก เปลี่ยนจากรายการได้ถ้าต้องการ
  4. คัดลอก JSON ไปใส่ในตัวอย่าง Swagger ไฟล์ .http หรือ request body ของ xUnit ตัวเลือกที่เลือกไว้จะถูกบันทึกใน URL

ตัวอย่าง

อินพุต (C#)
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 }
เอาต์พุต (JSON · camelCase)
{
  "id": "00000000-0000-0000-0000-000000000000",
  "sku": "",
  "stock_qty": 0,
  "state": 0,
  "updatedAt": "1970-01-01T00:00:00+00:00",
  "barcodes": [
    ""
  ]
}

ภายใต้นโยบาย camelCase ชื่อที่เป็นตัวพิมพ์ใหญ่ทั้งหมดอย่าง SKU จะกลายเป็น sku ตรงกับ JsonNamingPolicy.CamelCase ของ System.Text.Json ขณะที่ [JsonPropertyName("stock_qty")] คงชื่อเดิมไม่ว่าจะใช้นโยบายใด WarehouseNote ([JsonIgnore]) และฟิลด์ private อย่าง _version ไม่ถูกนำมาแสดง ส่วน enum State ไม่มี string converter จึงแสดงเป็น 0 ซึ่งเป็นค่าตัวเลขของค่าเริ่มต้น StockState.InStock

ฟีเจอร์ที่รองรับ

  • attribute สำหรับเปลี่ยนชื่อ: [JsonPropertyName] ของ System.Text.Json, [JsonProperty] ของ Newtonsoft และ [DataMember(Name = ...)]
  • รวมเฉพาะพร็อพเพอร์ตีและฟิลด์ที่เป็น public บวกกับสมาชิกที่ไม่ใช่ public แต่ติด [JsonInclude] ส่วน static, const, [JsonIgnore] และ [IgnoreDataMember] จะถูกตัดออก แต่การ ignore แบบมีเงื่อนไขอย่าง Condition = WhenWritingNull ยังคงแสดงอยู่
  • รองรับ positional record (record Customer(long Id, string Name)) และการระบุเป้าหมาย [property: JsonPropertyName(...)]
  • พร็อพเพอร์ตีคำนวณแบบ expression-bodied (=> ...) ถูกรวมไว้ด้วย เหมือนที่ System.Text.Json serialize จริง
  • enum ถูกเขียนเป็นตัวเลขตามค่าเริ่มต้นของ System.Text.Json และ Newtonsoft (รวมค่าที่กำหนดเองอย่าง = 10) ถ้ามี [JsonConverter(typeof(JsonStringEnumConverter))] (หรือ StringEnumConverter ของ Newtonsoft) บน enum หรือพร็อพเพอร์ตี หรือมี [JsonStringEnumMemberName] / [EnumMember(Value = ...)] บนสมาชิก จะใช้ชื่อเป็นสตริงแทน
  • วันที่และ ID: 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" และ object, JsonElement, JObject จะเป็น null
  • ค่าเริ่มต้นที่เป็น literal (= 1.5, = "KRW") ถูกใช้เป็นค่าตัวอย่าง

กรณีการใช้งาน

ทำให้ตัวอย่างใน Swashbuckle ตรงกับ response จริง

DTO ที่ใช้ [JsonPropertyName] ปนกับการตั้งชื่อแบบค่าเริ่มต้นทำให้ตัวอย่างที่ Swagger UI สร้างให้อ่านผิดได้ง่าย นำผลลัพธ์นี้ไปใช้ใน ISchemaFilter หรือคอมเมนต์ XML <example> เพื่อให้เอกสารกับ response ใช้คีย์ชุดเดียวกัน

ย้ายจาก Newtonsoft ไป System.Text.Json

สลับ นโยบายการตั้งชื่อ ไปมาบนโมเดลเดียวกันเพื่อดูล่วงหน้าว่าตัวพิมพ์ของคีย์จะเปลี่ยนอย่างไรหลังย้าย

ตรวจสัญญาระหว่างไคลเอนต์ Unity/MAUI กับเซิร์ฟเวอร์

เมื่อไคลเอนต์และเซิร์ฟเวอร์ต่างก็มีสำเนาโมเดลของตัวเอง ให้สร้าง JSON จากทั้งสองฝั่งแล้วเทียบกัน จะเห็นชื่อคีย์ที่ไม่ตรงกันได้อย่างรวดเร็ว

ข้อควรระวังและข้อจำกัด

  • JsonStringEnumConverter ที่ลงทะเบียนแบบ global ด้วย AddJsonOptions ใน Program.cs มองไม่เห็นจากโค้ดโมเดล enum จึงยังออกมาเป็นตัวเลข ถ้าอยากเห็นเป็นชื่อ ให้เพิ่ม [JsonConverter(typeof(JsonStringEnumConverter))] ที่การประกาศ enum ก่อนวาง
  • nullable reference type อย่าง string? จะได้ค่าตัวอย่างตามไทป์ ไม่ใช่ null
  • [JsonConverter] แบบกำหนดเองอื่นนอกจาก enum string converter, DefaultIgnoreCondition ใน JsonSerializerOptions และนโยบาย snake_case (JsonNamingPolicy.SnakeCaseLower) จะไม่ถูกนำมาใช้
  • ไม่รองรับ polymorphism ผ่าน [JsonPolymorphic]/[JsonDerivedType] จะสร้างเฉพาะ base type ที่ประกาศไว้

คำถามที่พบบ่อย

ควรใช้ตัวเลือกไหนของ นโยบายการตั้งชื่อ เมื่อไร?

ASP.NET Core Web API ใช้ JsonSerializerDefaults.Web ซึ่งเป็น camelCase ส่วนแอป console ที่เรียก JsonSerializer.Serialize โดยไม่ส่ง options หรือ Newtonsoft.Json ที่ใช้ค่าเริ่มต้น จะคงชื่อพร็อพเพอร์ตีไว้ กรณีนั้นให้เลือก ใช้ชื่อพร็อพเพอร์ตีตามเดิม

ทำไมพร็อพเพอร์ตีคำนวณอย่าง public string FullName => ... ถึงโผล่มา?

ทั้ง System.Text.Json และ Newtonsoft.Json serialize พร็อพเพอร์ตี public ที่มี getter ดังนั้นพร็อพเพอร์ตีคำนวณก็จะอยู่ใน response ด้วย ถ้าไม่ต้องการให้ส่งออกไป ให้ใส่ [JsonIgnore]

ใส่ [JsonPropertyName] บนพารามิเตอร์แบบ positional ของ record แล้วตอนรันจริงคีย์ไม่เปลี่ยนชื่อ

ถ้าไม่ระบุเป้าหมาย คอมไพเลอร์จะใช้ attribute กับพารามิเตอร์ของ constructor เท่านั้น เครื่องมือนี้รู้จักทั้งสองแบบ แต่ถ้าต้องการให้พร็อพเพอร์ตีที่ถูก serialize เปลี่ยนชื่อแน่นอน ให้เขียน [property: JsonPropertyName("...")]

ทำไมค่า DateTime ไม่มี Z ต่อท้าย?

DateTime ที่เป็น DateTimeKind.Unspecified จะถูก serialize โดยไม่มี offset ถ้าต้องการ offset UTC ที่ชัดเจน DateTimeOffset จะให้รูปแบบ +00:00