Chuyển class Kotlin sang JSON!

Dán mã Kotlin (data class) để nhận JSON mẫu! Hỗ trợ kotlinx.serialization @SerialName, Jackson, Gson, Moshi. Hữu ích cho tài liệu API và request body thử nghiệm (mock request body).
Kotlin
Kết quả
 

Chuyển class Kotlin sang JSON!

Dán một data class Kotlin có sẵn để xem nó trông như thế nào sau khi serialize, dưới dạng một tài liệu JSON mẫu. Class lồng nhau, property List/Map và enum đều được lần theo và điền giá trị, còn annotation đổi tên như @SerialName được áp dụng cho key.

Hãy dùng nó khi server và app dùng chung model và bạn cần xác nhận một class thực sự gửi và nhận JSON nào, hoặc khi tài liệu API hay mock server cần một body request mẫu.

Cách sử dụng

  1. Dán mã nguồn Kotlin. Các dòng import/package và hàm thành viên có thể để lại; chúng được bỏ qua.
  2. Phần lớn trường hợp hãy để Kiểu gốc ở Tự động: class đầu tiên không bị class khác tham chiếu sẽ thành gốc. Bạn cũng có thể chọn một class cụ thể trong danh sách.
  3. Sao chép JSON vào example của Swagger, body request của Postman hoặc test fixture.
  4. Kiểu được định nghĩa ở nơi khác (chẳng hạn class Money từ file khác) ra dạng null, và tên của chúng được liệt kê bên cạnh các option. Dán thêm các class đó là chúng được điền giá trị.

Ví dụ

Đầu vào (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,
}
Đầu ra (JSON)
{
  "id": 0,
  "title": "",
  "author_name": "",
  "status": "draft",
  "tags": [
    ""
  ],
  "publishedAt": "1970-01-01T00:00:00Z"
}

authorName được xuất thành author_name nhờ @SerialName, và giá trị mặc định PostStatus.DRAFT được phân giải thành "draft" qua @SerialName riêng của entry enum đó. cachedHtml được đánh dấu @Transient nên bị bỏ. Property nullable có mặc định null, như publishedAt, vẫn nhận giá trị mẫu theo kiểu (Instant → timestamp ISO) chứ không phải null.

Tính năng hỗ trợ

  • Đổi tên key: @SerialName của kotlinx.serialization, @JsonProperty của Jackson, @SerializedName của Gson và @Json(name = ...) của Moshi.
  • Bị loại: property có @Transient hoặc @JsonIgnore, property private, property ủy quyền như by lazy, computed property chỉ có getter, giá trị const và member của companion object.
  • Giá trị mặc định là literal chuỗi, số hay boolean được dùng làm giá trị mẫu; mặc định như Status.PAID thành giá trị JSON của entry đó.
  • Enum dùng entry đầu tiên, có tôn trọng @SerialName ở cấp entry.
  • Ngày và giờ: LocalDate → 1970-01-01, LocalDateTime → 1970-01-01T00:00:00, Instant/OffsetDateTime → chuỗi ISO kết thúc bằng Z, Duration → PT0S; UUID nhận giá trị đúng định dạng.
  • List, Set và Array có một phần tử mẫu; map có kiểu key là số như Map<Int, V> dùng "0" làm key.
  • Class tự tham chiếu (cây, comment dạng luồng) được cắt bằng null hoặc mảng rỗng thay vì mở rộng vô hạn.

Trường hợp sử dụng

Tài liệu API cho service Ktor hoặc Spring

Dán một DTO response là có khung JSON cho example của OpenAPI hoặc README. Field đổi tên qua @SerialName xuất hiện đúng dưới cái tên mà serializer sẽ thực sự ghi ra.

Response giả cho test Android

Dựng body cho MockWebServer hoặc JSON fixture cục bộ từ chính model mà interface Retrofit trả về. Thay các giá trị giữ chỗ ("", 0) bằng dữ liệu thực tế mà cấu trúc vẫn khớp với model.

Thống nhất tên key với backend

Cho đội server thấy chính xác những gì app gửi đi, hoặc so một spec nhận được với model Kotlin để bắt lỗi lệch tên key trước khi chúng thành lỗi runtime.

Lưu ý và giới hạn

  • Giá trị là giá trị giữ chỗ theo kiểu ("", 0, false), không phải dữ liệu thực tế; hãy thay chúng trước khi công bố tài liệu.
  • Property nullable (String?) cũng nhận giá trị mẫu theo kiểu thay vì null, nên hãy đánh dấu riêng những field thực sự có thể là null.
  • Quy tắc đặt tên toàn cục như @JsonNaming của Jackson hay JsonNamingStrategy của kotlinx không được áp dụng; property không có annotation giữ tên Kotlin làm key.
  • Phân cấp sealed đa hình (discriminator type) và KSerializer tùy biến không được phản ánh.
  • Giá trị mặc định dựng từ lời gọi hàm, như emptyList() hay listOf(...), không được tính; giá trị lấy theo kiểu đã khai báo.

Câu hỏi thường gặp

Property @Transient bị thiếu trong output. Như vậy có đúng không?

Đúng. @Transient của kotlinx.serialization và @JsonIgnore của Jackson giữ field ngoài quá trình serialize, nên mẫu cũng bỏ nó. private val khai báo trong thân class bị bỏ ra vì cùng lý do.

Có đọc được model viết cho Gson hay Moshi không?

Cú pháp class giống nhau nên parse bình thường. Việc đổi tên từ @SerializedName("...") của Gson và @Json(name = "...") của Moshi đều được nhận ra.

Tôi đã khai báo = null, sao field vẫn có giá trị?

Mục tiêu là cho thấy hình dạng của từng field, nên mặc định null bị bỏ qua và giá trị mẫu theo kiểu được dùng. Nhờ vậy bạn thấy được, chẳng hạn, một Instant? được truyền đi dưới định dạng chuỗi nào.

Class của tôi nằm ở nhiều file. Nên dán gì?

Dán lần lượt từng file vào cùng một ô nhập. Kiểu nào vẫn còn thiếu sẽ được nêu tên cạnh các option, cho bạn biết cần thêm gì nữa.