JPAエンティティをJSONに変換!

JPAエンティティを入力するとサンプルJSONを作ります!JPA @Entity, Hibernate, Spring Boot 対応。API ドキュメントやテスト用のリクエストボディ(sample JSON)に。
JPA
結果
 

JPAエンティティをJSONに変換!

Spring Boot JPA の @Entity クラスを貼り付けると、コントローラーがそのエンティティを返したときに Jackson が作る形の例の JSON を確認できます。フィールド名、@JsonIgnore と @JsonProperty、@MappedSuperclass から継承したフィールド、Java 8 の日付型を、Spring Boot の既定の Jackson 設定に従って処理します。

REST Docs や Swagger の例、Postman のリクエストボディに使ったり、DTO なしでエンティティを公開したときにどのフィールドが漏れ出すかを点検したりするのに使ってください。

使い方

  1. JPA 欄にエンティティクラスを貼り付けます。import や Lombok のアノテーションは残したままで構いません。値が埋まるよう、親クラス、関連エンティティ、enum も含めてください。
  2. 他のどのクラスからも参照されていないクラスがルートになります。エンティティ同士が互いに参照している場合は public クラスが選ばれます。
  3. 結果をコピーして、テストやドキュメントに使います。

例

入力 (Java · JPA)
@MappedSuperclass
public abstract class BaseEntity {
    @Id @GeneratedValue
    private Long id;
    private LocalDateTime createdAt;
}

@Entity
public class Appointment extends BaseEntity {
    private LocalDate visitDate;
    private BigDecimal fee;
    @Enumerated(EnumType.STRING)
    private Status status;
    @ManyToOne(fetch = FetchType.LAZY)
    private Patient patient;

    public enum Status { BOOKED, DONE, CANCELED }
}

@Entity
class Patient extends BaseEntity {
    private String name;
    @JsonIgnore
    private String residentNumber;
    @OneToMany(mappedBy = "patient")
    private List<Appointment> appointments;
}
出力 (JSON)
{
  "id": 0,
  "createdAt": "1970-01-01T00:00:00",
  "visitDate": "1970-01-01",
  "fee": 0,
  "status": "BOOKED",
  "patient": {
    "id": 0,
    "createdAt": "1970-01-01T00:00:00",
    "name": "",
    "appointments": []
  }
}

Appointment と Patient は互いに参照しているので、public クラスの Appointment がルートになり、Patient.appointments は無限ループせず空の配列で打ち切られます。BaseEntity の id と createdAt が先頭に来て、residentNumber は @JsonIgnore によって消えています。LocalDateTime はオフセットのない ISO 文字列で、enum は最初の定数 "BOOKED" を示しています。

対応機能

  • static や transient のフィールド、@JsonIgnore のフィールド、クラスに付けた @JsonIgnoreProperties({"..."}) に挙げた名前は飛ばします。
  • @JsonProperty("doctor_name") は JSON のキー名を変えます。
  • 親クラス(@MappedSuperclass や任意の extends)が入力にあれば、そのフィールドが先に並びます。
  • private Status status = Status.ACTIVE; や private int visits = 0; のようなエンティティのデフォルト値はその値で表示され、裏付けるフィールドのない計算 getter(public int getAge())も、Jackson が出力するのと同じく追加のキーとして現れます。
  • 日付の出力は Spring Boot の既定に従います: LocalDate → 1970-01-01、LocalDateTime → 1970-01-01T00:00:00、java.util.Date → 1970-01-01T00:00:00.000+00:00。
  • BigDecimal や Long などの数値ラッパーは 0、UUID はすべてゼロの UUID、byte[] は Base64 文字列の "AA==" になります。
  • List/Set は要素1つの配列、Map<Long, String> はキーの型に合わせたオブジェクト({"0": ""})になり、Optional<T> は内側の値に展開されます。
  • 双方向の関連(@OneToMany と @ManyToOne)は、ループして戻ってくる箇所で null や空の配列で打ち切ります。

利用シーン

Spring REST Docs や Swagger の例

エンティティから直接 @Schema(example = ...) やドキュメントのスニペット用の JSON を生成し、フィールドが変わるたびに貼り直せば、ドキュメントを同期させておけます。

公開しているエンティティの点検

DTO なしでエンティティを返している場合、パスワードやマイナンバーのようなフィールドがレスポンスに含まれていないか確認できます。出力にあるフィールドは、Jackson がシリアライズするフィールドです。

MockMvc のリクエストボディ

出力を mockMvc.perform(post("/appointments").content(...)) の骨組みとして使い、生成された id やタイムスタンプを削除してから値を埋めてください。

注意点と制限

  • 実際の Jackson は双方向の関連で無限に再帰します(StackOverflowError)。出力が途中で打ち切られているように見えたら、@JsonManagedReference/@JsonBackReference、@JsonIgnore、DTO を検討する合図です。
  • JPA の @Transient アノテーションは既定では Jackson に無視されないので、そうしたフィールドは出力に残ります。削除されるのは Java の transient キーワードを付けたフィールドだけです。
  • FetchType.LAZY の関連は、実際には Hibernate のプロキシとしてシリアライズに失敗することがあります。出力はすべてが読み込まれている前提です。
  • 入力にないクラスを型に持つフィールドは null で表示され、nullable や length のような @Column の制約は反映されません。

よくある質問

日付は [2024,1,1] のような配列ではなく、本当に文字列ですか?

Spring Boot は WRITE_DATES_AS_TIMESTAMPS を無効にしているので、LocalDateTime は ISO 文字列で書き出されます。JavaTimeModule だけを登録して自分で組み立てた ObjectMapper では、配列で書き出されることがあります。

Lombok の @Getter がなくても、すべてのフィールドが出てきますか?

このツールはフィールド宣言をもとに動きます。実際の Jackson は既定で getter(または public フィールド)を通してシリアライズするので、getter のない private フィールドは実際のレスポンスには含まれないことがあります。

MongoDB の @Document クラスも貼り付けられますか?

同じ Jackson のルールに従いますが、ObjectId や @Field のような MongoDB 特有の注意点は Spring Data MongoDB → JSON のページで扱っています。