Kotlin کلاسز کو JSON میں تبدیل کریں!

Kotlin (data class) کوڈ ڈالیں اور مثالی JSON حاصل کریں! kotlinx.serialization @SerialName, Jackson, Gson, Moshi سپورٹ۔ API دستاویزات اور ٹیسٹ request body (sample JSON) کے لیے مفید۔
Kotlin
نتیجہ
 

Kotlin کلاسز کو JSON میں تبدیل کریں!

موجودہ Kotlin data class پیسٹ کریں اور نمونہ JSON document کی صورت میں دیکھیں کہ serialize ہونے کے بعد وہ کیسی دکھتی ہے۔ nested کلاسز، List/Map properties اور enums کو فالو کر کے بھرا جاتا ہے، اور @SerialName جیسی نام بدلنے والی annotations keys پر لاگو ہوتی ہیں۔

اسے تب استعمال کریں جب سرور اور ایپ ماڈلز شیئر کرتے ہوں اور آپ کو تصدیق کرنی ہو کہ کوئی کلاس واقعی کون سا JSON بھیجتی اور وصول کرتی ہے، یا جب API doc یا mock server کو request body کا نمونہ چاہیے۔

استعمال کا طریقہ

  1. اپنا Kotlin source پیسٹ کریں۔ import/package لائنیں اور member functions رہنے دیں؛ وہ چھوڑ دی جاتی ہیں۔
  2. زیادہ تر صورتوں میں روٹ ٹائپ کو خودکار پر رہنے دیں: جس پہلی کلاس کا کوئی دوسری کلاس حوالہ نہ دے وہ root بنتی ہے۔ آپ فہرست سے کوئی خاص کلاس بھی چن سکتے ہیں۔
  3. JSON کو Swagger example، Postman request body یا test fixture میں کاپی کریں۔
  4. کہیں اور بیان کی گئی types (مثلاً کسی دوسری فائل کی Money کلاس) null کی صورت میں آتی ہیں، اور ان کے نام options کے ساتھ درج ہوتے ہیں۔ وہ کلاسز بھی پیسٹ کریں تو وہ بھی بھر جاتی ہیں۔

مثال

ان پٹ (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"
}

@SerialName کی وجہ سے authorName، author_name کے طور پر لکھا جاتا ہے، اور ڈیفالٹ PostStatus.DRAFT، enum entry کے اپنے @SerialName کے ذریعے "draft" بنتا ہے۔ cachedHtml پر @Transient ہے، اس لیے وہ ہٹا دیا جاتا ہے۔ publishedAt جیسی nullable property جس کا ڈیفالٹ null ہو، پھر بھی null کے بجائے typed نمونہ (Instant → ISO timestamp) پاتی ہے۔

معاون خصوصیات

  • keys کے نام کی تبدیلی: kotlinx.serialization کا @SerialName، Jackson کا @JsonProperty، Gson کا @SerializedName اور Moshi کا @Json(name = ...)۔
  • خارج: @Transient یا @JsonIgnore والی properties، private properties، by lazy جیسی delegated properties، صرف getter والی computed properties، const values اور companion object members۔
  • string، نمبر اور boolean والے literal defaults نمونہ value کے طور پر استعمال ہوتے ہیں؛ Status.PAID جیسا ڈیفالٹ اس entry کی JSON value بنتا ہے۔
  • enums اپنی پہلی entry استعمال کرتے ہیں، entry کی سطح کے @SerialName کا لحاظ رکھتے ہوئے۔
  • تاریخ اور وقت: LocalDate → 1970-01-01، LocalDateTime → 1970-01-01T00:00:00، Instant/OffsetDateTime → Z پر ختم ہونے والی ISO string، Duration → PT0S؛ UUID کو درست شکل والی value ملتی ہے۔
  • List، Set اور Array کو ایک نمونہ element ملتا ہے؛ Map<Int, V> جیسی عددی key type والا map، key کے طور پر "0" استعمال کرتا ہے۔
  • خود کا حوالہ دینے والی کلاسز (trees، threaded comments) لامتناہی پھیلنے کے بجائے null یا خالی array پر کاٹ دی جاتی ہیں۔

استعمال کے کیس

Ktor یا Spring سروسز کی API documentation

response DTO پیسٹ کریں اور OpenAPI example یا README کے لیے JSON کا ڈھانچہ تیار ہے۔ @SerialName سے نام بدلے گئے فیلڈز اسی نام سے آتے ہیں جو serializer اصل میں لکھے گا۔

Android ٹیسٹس کے لیے جعلی responses

MockWebServer یا local JSON fixture کی body اسی ماڈل سے بنائیں جو آپ کا Retrofit interface لوٹاتا ہے۔ placeholder values (""، 0) کو حقیقت سے قریب ڈیٹا سے بدلیں، ڈھانچہ پھر بھی ماڈل سے میل کھاتا ہے۔

بیک اینڈ کے ساتھ key ناموں پر اتفاق

سرور ٹیم کو بالکل وہ دکھائیں جو ایپ بھیجتی ہے، یا موصول شدہ spec کو اپنے Kotlin ماڈل سے ملا کر key ناموں کی عدم مطابقت runtime errors بننے سے پہلے پکڑیں۔

نوٹس اور حدود

  • values، type کے placeholders (""، 0، false) ہیں، حقیقی ڈیٹا نہیں؛ docs شائع کرنے سے پہلے انہیں بدلیں۔
  • nullable properties (String?) کو بھی null کے بجائے typed نمونہ ملتا ہے، اس لیے الگ سے نشان لگائیں کہ کون سے فیلڈز واقعی null ہو سکتے ہیں۔
  • Jackson کا @JsonNaming یا kotlinx کا JsonNamingStrategy جیسے global naming قواعد لاگو نہیں ہوتے؛ بغیر annotation والی properties اپنا Kotlin نام ہی key کے طور پر رکھتی ہیں۔
  • polymorphic sealed hierarchies (type discriminator) اور custom KSerializers کا اثر نہیں دکھایا جاتا۔
  • emptyList() یا listOf(...) جیسی function calls سے بنے defaults evaluate نہیں ہوتے؛ value اس کے بجائے ڈکلیئر کی گئی type سے آتی ہے۔

عام سوالات

@Transient property آؤٹ پٹ سے غائب ہے۔ کیا یہ متوقع ہے؟

جی ہاں۔ kotlinx.serialization کا @Transient اور Jackson کا @JsonIgnore فیلڈ کو serialization سے باہر رکھتے ہیں، اس لیے نمونہ بھی اسے چھوڑ دیتا ہے۔ کلاس body میں ڈکلیئر کیا گیا private val بھی اسی وجہ سے نکال دیا جاتا ہے۔

کیا یہ Gson یا Moshi کے لیے لکھے ماڈلز پڑھتا ہے؟

کلاس کا syntax ایک جیسا ہے، اس لیے وہ ٹھیک parse ہوتے ہیں۔ Gson کے @SerializedName("...") اور Moshi کے @Json(name = "...") سے نام کی تبدیلیاں پہچانی جاتی ہیں۔

میں نے = null ڈکلیئر کیا تھا، پھر فیلڈ میں value کیوں ہے؟

مقصد ہر فیلڈ کی شکل دکھانا ہے، اس لیے null ڈیفالٹ نظر انداز کر کے typed نمونہ استعمال کیا جاتا ہے۔ اس طرح آپ دیکھ سکتے ہیں، مثلاً، کہ Instant? کس string format میں جاتا ہے۔

میری کلاسز کئی فائلوں میں ہیں۔ کیا پیسٹ کروں؟

انہیں ایک کے بعد ایک اسی ان پٹ میں پیسٹ کریں۔ جو type ابھی بھی غائب ہو اس کا نام options کے ساتھ آتا ہے، جس سے پتا چلتا ہے کہ اور کیا شامل کرنا ہے۔