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

วางโค้ด Kotlin (data class) แล้วรับ JSON ตัวอย่าง! รองรับ kotlinx.serialization @SerialName, Jackson, Gson, Moshi เหมาะสำหรับเอกสาร API และ request body สำหรับทดสอบ (mock request body)
Kotlin
ผลลัพธ์
 

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

วาง data class ของ Kotlin ที่มีอยู่แล้วเพื่อดูว่าเมื่อ serialize แล้วจะหน้าตาเป็นอย่างไรในรูป JSON ตัวอย่าง คลาสที่ซ้อนกัน พร็อพเพอร์ตี List/Map และ enum จะถูกตามไปเติมค่า และ annotation ที่เปลี่ยนชื่ออย่าง @SerialName ถูกนำมาใช้กับคีย์

ใช้เมื่อเซิร์ฟเวอร์และแอปใช้โมเดลร่วมกันและต้องการยืนยันว่าคลาสหนึ่งส่งและรับ JSON แบบไหนจริง ๆ หรือเมื่อเอกสาร API หรือ mock server ต้องการตัวอย่าง request body

วิธีใช้

  1. วางซอร์ส Kotlin บรรทัด import/package และฟังก์ชันสมาชิกไม่ต้องลบ จะถูกข้ามไป
  2. ส่วนใหญ่ปล่อย ชนิดราก เป็น อัตโนมัติ ได้ คลาสแรกที่ไม่ถูกคลาสอื่นอ้างถึงจะเป็นราก หรือจะเลือกคลาสเฉพาะจากรายการก็ได้
  3. คัดลอก JSON ไปใส่ในตัวอย่าง Swagger, request body ของ Postman หรือ test fixture
  4. ไทป์ที่นิยามไว้ที่อื่น (เช่นคลาส Money จากไฟล์อื่น) จะออกมาเป็น null และชื่อของมันจะถูกแสดงข้างตัวเลือก วางคลาสเหล่านั้นเพิ่มแล้วจะถูกเติมค่าให้

ตัวอย่าง

อินพุต (Kotlin)
@Serializable
data class Article(
    val id: Long,
    val title: String,
    @SerialName("author_name") val authorName: String,
    val status: PostStatus = PostStatus.DRAFT,
    val tags: List<String> = emptyList(),
    val publishedAt: Instant? = null,
    @Transient val cachedHtml: String = "",
)

@Serializable
enum class PostStatus {
    @SerialName("draft") DRAFT,
    @SerialName("published") PUBLISHED,
}
เอาต์พุต (JSON)
{
  "id": 0,
  "title": "",
  "author_name": "",
  "status": "draft",
  "tags": [
    ""
  ],
  "publishedAt": "1970-01-01T00:00:00Z"
}

authorName ถูกเขียนเป็น author_name เพราะ @SerialName และค่าเริ่มต้น PostStatus.DRAFT กลายเป็น "draft" ผ่าน @SerialName ของ entry ใน enum เอง cachedHtml ติด @Transient จึงถูกตัดออก พร็อพเพอร์ตี nullable ที่ค่าเริ่มต้นเป็น null อย่าง publishedAt ยังได้ค่าตัวอย่างตามไทป์ (Instant → timestamp แบบ ISO) ไม่ใช่ null

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

  • การเปลี่ยนชื่อคีย์: @SerialName ของ kotlinx.serialization, @JsonProperty ของ Jackson, @SerializedName ของ Gson และ @Json(name = ...) ของ Moshi
  • สิ่งที่ถูกตัดออก: พร็อพเพอร์ตีที่ติด @Transient หรือ @JsonIgnore พร็อพเพอร์ตี private พร็อพเพอร์ตีแบบ delegate อย่าง by lazy พร็อพเพอร์ตีคำนวณที่มีแค่ getter ค่า const และสมาชิกของ companion object
  • ค่าเริ่มต้นที่เป็น literal ของสตริง ตัวเลข และบูลีนถูกใช้เป็นค่าตัวอย่าง ค่าเริ่มต้นอย่าง Status.PAID จะกลายเป็นค่า JSON ของ entry นั้น
  • enum ใช้ entry แรก โดยเคารพ @SerialName ระดับ entry
  • วันที่และเวลา: LocalDate → 1970-01-01, LocalDateTime → 1970-01-01T00:00:00, Instant/OffsetDateTime → สตริง ISO ที่ลงท้ายด้วย Z, Duration → PT0S และ UUID ได้ค่าที่รูปแบบถูกต้อง
  • List, Set และ Array ได้สมาชิกตัวอย่างหนึ่งตัว map ที่คีย์เป็นไทป์ตัวเลขอย่าง Map<Int, V> ใช้ "0" เป็นคีย์
  • คลาสที่อ้างถึงตัวเอง (tree, คอมเมนต์แบบ thread) ถูกตัดด้วย null หรืออาร์เรย์ว่าง แทนที่จะขยายไม่สิ้นสุด

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

เอกสาร API สำหรับเซอร์วิส Ktor หรือ Spring

วาง response DTO แล้วจะได้โครง JSON สำหรับ example ของ OpenAPI หรือ README ฟิลด์ที่เปลี่ยนชื่อผ่าน @SerialName จะแสดงด้วยชื่อเดียวกับที่ serializer เขียนออกจริง

response ปลอมสำหรับเทสต์ Android

สร้าง body สำหรับ MockWebServer หรือ JSON fixture ในเครื่องจากโมเดลตัวเดียวกับที่ interface ของ Retrofit คืนค่า เปลี่ยนค่าตัวอย่าง ("", 0) เป็นข้อมูลที่สมจริงแล้วโครงสร้างก็ยังตรงกับโมเดล

ตกลงชื่อคีย์กับ backend

แสดงให้ทีมเซิร์ฟเวอร์เห็นว่าแอปส่งอะไรไปจริง ๆ หรือเทียบสเปกที่ได้รับกับโมเดล Kotlin เพื่อจับชื่อคีย์ที่ไม่ตรงกันก่อนจะกลายเป็น error ตอนรัน

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

  • ค่าเป็นค่าตัวอย่างตามไทป์ ("", 0, false) ไม่ใช่ข้อมูลที่สมจริง ให้เปลี่ยนก่อนเผยแพร่เอกสาร
  • พร็อพเพอร์ตี nullable (String?) ก็ได้ค่าตัวอย่างตามไทป์ ไม่ใช่ null จึงควรระบุแยกว่าฟิลด์ไหนอาจเป็น null จริง
  • กฎการตั้งชื่อแบบ global อย่าง @JsonNaming ของ Jackson หรือ JsonNamingStrategy ของ kotlinx ไม่ถูกนำมาใช้ พร็อพเพอร์ตีที่ไม่มี annotation ใช้ชื่อใน Kotlin เป็นคีย์
  • ลำดับชั้น sealed แบบ polymorphic (ตัวแยกแยะ type) และ KSerializer แบบกำหนดเองไม่ถูกสะท้อนในผลลัพธ์
  • ค่าเริ่มต้นที่สร้างจากการเรียกฟังก์ชันอย่าง emptyList() หรือ listOf(...) ไม่ถูกประมวลผล ค่าจะมาจากไทป์ที่ประกาศแทน

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

พร็อพเพอร์ตี @Transient หายไปจากผลลัพธ์ เป็นเรื่องปกติไหม?

ปกติ @Transient ของ kotlinx.serialization และ @JsonIgnore ของ Jackson กันฟิลด์ไม่ให้ถูก serialize ตัวอย่างจึงตัดออกด้วย private val ที่ประกาศในตัวคลาสก็ถูกตัดออกด้วยเหตุผลเดียวกัน

อ่านโมเดลที่เขียนสำหรับ Gson หรือ Moshi ได้ไหม?

ไวยากรณ์ของคลาสเหมือนกัน จึงพาร์สได้ปกติ การเปลี่ยนชื่อจาก @SerializedName("...") ของ Gson และ @Json(name = "...") ของ Moshi ก็รู้จัก

ประกาศ = null ไว้ แล้วทำไมฟิลด์ยังมีค่า?

เป้าหมายคือแสดงรูปร่างของแต่ละฟิลด์ ค่าเริ่มต้น null จึงถูกข้ามและใช้ค่าตัวอย่างตามไทป์แทน ทำให้เห็นได้ เช่น ว่า Instant? ถูกส่งเป็นสตริงรูปแบบไหน

คลาสอยู่หลายไฟล์ ควรวางอะไร?

วางต่อกันลงในอินพุตเดียวกัน ไทป์ที่ยังขาดจะถูกระบุชื่อไว้ข้างตัวเลือก ซึ่งบอกว่าต้องเพิ่มอะไรอีก