Kotlin クラスを JSON に変換しよう!

Kotlin の data class コードを入力すると例の JSON を作ります!kotlinx.serialization @SerialName, Jackson, Gson, Moshi 対応。API ドキュメントやテスト用のリクエストボディ(sample JSON)に。
Kotlin
結果
 

Kotlin クラスを JSON に変換しよう!

既存の Kotlin の data class を貼り付けると、シリアライズしたときの姿をサンプルの JSON ドキュメントとして確認できます。ネストしたクラス、List/Map のプロパティ、enum もたどって埋め、@SerialName などの名前を変えるアノテーションをキーに反映します。

サーバーとアプリでモデルを共有していて、クラスが実際にどんな JSON を送受信するのかを確かめたいときや、API ドキュメントやモックサーバーにリクエストボディのサンプルが必要なときに使ってください。

使い方

  1. Kotlin のソースを貼り付けます。import/package の行やメンバー関数は残したままで構いません。読み飛ばされます。
  2. ほとんどの場合、ルート型 は 自動 のままで大丈夫です。他のクラスから参照されていない最初のクラスがルートになります。リストから特定のクラスを選ぶこともできます。
  3. JSON をコピーして、Swagger の例、Postman のリクエストボディ、テストフィクスチャに使います。
  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 は @SerialName によって author_name として出力され、デフォルト値の PostStatus.DRAFT は enum エントリー自身の @SerialName を通して "draft" になります。cachedHtml は @Transient が付いているので除外されます。publishedAt のようにデフォルトが null の nullable プロパティにも、null ではなく型に応じたサンプル(Instant → ISO タイムスタンプ)が入ります。

対応機能

  • キー名の変更: kotlinx.serialization の @SerialName、Jackson の @JsonProperty、Gson の @SerializedName、Moshi の @Json(name = ...)。
  • 除外されるもの: @Transient や @JsonIgnore の付いたプロパティ、private プロパティ、by lazy のような委譲プロパティ、getter だけの計算プロパティ、const 値、companion object のメンバー。
  • 文字列・数値・真偽値のリテラルのデフォルト値はサンプル値として使い、Status.PAID のようなデフォルトはそのエントリーの JSON 値になります。
  • enum は、エントリーに付いた @SerialName を考慮したうえで最初のエントリーを使います。
  • 日付と時刻: LocalDate → 1970-01-01、LocalDateTime → 1970-01-01T00:00:00、Instant/OffsetDateTime → Z で終わる ISO 文字列、Duration → PT0S。UUID には正しい形式の値が入ります。
  • List、Set、Array は要素を1つ持ち、Map<Int, V> のように数値のキー型を持つマップは "0" をキーにします。
  • 自己参照するクラス(ツリー、スレッド形式のコメント)は、無限に展開せず null や空の配列で打ち切ります。

利用シーン

Ktor や Spring のサービスの API ドキュメント

レスポンス DTO を貼り付ければ、OpenAPI の example や README に使う JSON の骨組みが得られます。@SerialName で名前を変えたフィールドも、シリアライザーが実際に書き出す名前で表示されます。

Android テスト用の偽レスポンス

Retrofit のインターフェースが返すモデルそのものから、MockWebServer やローカルの JSON フィクスチャのボディを作れます。仮の値(""、0)を現実的なデータに差し替えても、構造はモデルと一致したままです。

バックエンドとキー名をすり合わせる

アプリが何を送るのかをサーバーチームに正確に見せたり、受け取った仕様を Kotlin のモデルと比べたりして、キー名の食い違いを実行時エラーになる前に見つけられます。

注意点と制限

  • 値は型ごとの仮の値(""、0、false)で、現実的なデータではありません。ドキュメントを公開する前に置き換えてください。
  • nullable なプロパティ(String?)にも null ではなく型に応じたサンプルが入るので、実際に null になりうるフィールドは別途明記してください。
  • Jackson の @JsonNaming や kotlinx の JsonNamingStrategy のようなグローバルな命名ルールは反映されません。アノテーションのないプロパティは Kotlin の名前がそのままキーになります。
  • ポリモーフィックな sealed 階層(type の識別子)や独自の KSerializer は反映されません。
  • emptyList() や listOf(...) のような関数呼び出しで作るデフォルト値は評価せず、宣言された型から値を作ります。

よくある質問

@Transient のプロパティが出力にありません。これで正しいですか?

正しいです。kotlinx.serialization の @Transient と Jackson の @JsonIgnore はフィールドをシリアライズの対象外にするので、サンプルからも省かれます。クラス本体で宣言した private val も同じ理由で除外されます。

Gson や Moshi 向けに書いたモデルも読めますか?

クラスの構文は同じなので、問題なく解析できます。Gson の @SerializedName("...") や Moshi の @Json(name = "...") による名前の変更も認識します。

= null と宣言したのに、フィールドに値が入っているのはなぜですか?

目的は各フィールドの形を見せることなので、null のデフォルト値は無視して型に応じたサンプルを使います。そのおかげで、たとえば Instant? がどんな文字列形式でやり取りされるかがわかります。

クラスが複数のファイルに分かれています。何を貼り付ければいいですか?

同じ入力欄に続けて貼り付けてください。まだ足りない型があればオプションの横に名前が表示されるので、何を追加すればよいかがわかります。