粘贴现有的 Kotlin data class,就能以示例 JSON 文档的形式看到它序列化后的样子。嵌套类、List/Map 属性和 enum 都会被跟踪并填充,@SerialName 等重命名注解也会应用到 key 上。
当服务器和应用共用模型、需要确认某个类实际收发的是什么 JSON 时,或者 API 文档、mock 服务器需要请求体示例时,就可以用它。
import/package 行和成员函数可以保留,它们会被跳过。根类型 保持为 自动:第一个没有被其他类引用的类会成为根。也可以从列表中选择特定的类。Money 类)会输出为 null,它们的名称会列在选项旁边。把这些类也粘贴进来,它们就会被填充。@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,
}{
"id": 0,
"title": "",
"author_name": "",
"status": "draft",
"tags": [
""
],
"publishedAt": "1970-01-01T00:00:00Z"
}由于 @SerialName,authorName 输出为 author_name;默认值 PostStatus.DRAFT 通过 enum 条目自身的 @SerialName 解析为 "draft"。cachedHtml 标记了 @Transient,因此被去掉。像 publishedAt 这样默认为 null 的可空属性,仍然会得到按类型生成的示例(Instant → ISO 时间戳),而不是 null。
@SerialName、Jackson 的 @JsonProperty、Gson 的 @SerializedName 以及 Moshi 的 @Json(name = ...)。@Transient 或 @JsonIgnore 的属性、private 属性、by lazy 这样的委托属性、只有 getter 的计算属性、const 值以及 companion object 成员。Status.PAID 这样的默认值会变成该条目的 JSON 值。@SerialName。LocalDate → 1970-01-01,LocalDateTime → 1970-01-01T00:00:00,Instant/OffsetDateTime → 以 Z 结尾的 ISO 字符串,Duration → PT0S;UUID 会得到格式正确的值。List、Set 和 Array 得到一个示例元素;Map<Int, V> 这样 key 为数值类型的 map 使用 "0" 作为 key。null 或空数组截断,而不会无限展开。粘贴响应 DTO,就有了 OpenAPI example 或 README 所需的 JSON 骨架。通过 @SerialName 改名的字段,会以序列化器实际写出的名称出现。
直接用 Retrofit 接口返回的那个模型,构造 MockWebServer 或本地 JSON fixture 的响应体。把占位值(""、0)换成真实感的数据,结构依然与模型一致。
准确地向服务端团队展示应用会发送什么,或者把收到的规格与 Kotlin 模型对照,在 key 名不一致变成运行时错误之前发现它。
""、0、false),而不是真实数据;发布文档前请替换。String?)同样会得到按类型生成的示例而不是 null,所以请另外标明哪些字段实际可能为 null。@JsonNaming 或 kotlinx 的 JsonNamingStrategy 等全局命名规则;没有注解的属性以 Kotlin 名称作为 key。type 鉴别字段)和自定义 KSerializer。emptyList() 或 listOf(...) 这样由函数调用构成的默认值不会被求值,值改由声明的类型决定。@Transient 属性,这正常吗?正常。kotlinx.serialization 的 @Transient 和 Jackson 的 @JsonIgnore 会把字段排除在序列化之外,所以示例中也省略了它。在类体中声明的 private val 出于同样的原因也会被省略。
类的语法相同,所以能正常解析。Gson 的 @SerializedName("...") 和 Moshi 的 @Json(name = "...") 所做的重命名都能识别。
= null,为什么字段还有值?目的是展示每个字段的形态,所以会忽略 null 默认值,改用按类型生成的示例。这样你就能看到,比如 Instant? 是以哪种字符串格式传输的。
把它们依次粘贴到同一个输入中。仍然缺失的类型会显示在选项旁边,告诉你还需要补充什么。