แปลงคลาส Java เป็น JSON!

วางโค้ด Java (class·record) แล้วรับ JSON ตัวอย่าง! รองรับ Jackson @JsonProperty, @JsonIgnore, Lombok เหมาะสำหรับเอกสาร API และ request body สำหรับทดสอบ (mock request body)
Java
ผลลัพธ์
 

แปลงคลาส Java เป็น JSON!

ใส่ซอร์สของ Java DTO, POJO หรือ record แล้วจะได้ JSON ที่ Jackson ตามค่าเริ่มต้นของ Spring Boot น่าจะสร้างออกมา คีย์มาจากฟิลด์ที่ประกาศไว้ โดยคำนึงถึง @JsonProperty, @JsonIgnore, @JsonIgnoreProperties และการตัดฟิลด์ static/transient ออก

ใช้สร้างตัวอย่างสำหรับ Swagger หรือ payload ตัวอย่างให้ฝั่ง frontend จาก request หรือ response DTO ของ controller หรือแค่เช็กว่าคลาสที่ใช้ Lombok @Data จะส่งคีย์อะไรออกมาบ้าง

วิธีใช้

  1. วางซอร์ส DTO ได้ตามที่เป็นอยู่ ไม่ต้องลบ import, annotation ของ Lombok, constructor หรือเมธอด
  2. ใส่การประกาศ static class, record และ enum ที่ซ้อนอยู่ไว้ในอินพุตเดียวกัน เพื่อให้ฟิลด์ที่อ้างถึงถูกเติมด้วยโครงสร้างของมัน
  3. เมื่อ ชนิดราก เป็น อัตโนมัติ จะเลือกคลาสที่ไม่มีคลาสอื่นใช้เป็นไทป์ของฟิลด์ ถ้า entity อ้างถึงกันไปมา ให้เลือกคลาสที่ต้องการจากรายการ
  4. คัดลอกผลลัพธ์ไปใส่ใน @Schema(example = ...), snippet ของ REST Docs หรือ request body ของ MockMvc

ตัวอย่าง

อินพุต (Java)
@Data
@JsonIgnoreProperties({"password"})
public class MemberResponse {
    private Long memberId;
    @JsonProperty("nick_name")
    private String nickname;
    private String password;
    private Grade grade = Grade.SILVER;
    private LocalDate birthDate;
    private List<Address> addresses;
    private static final long serialVersionUID = 1L;

    public enum Grade { BRONZE, SILVER, GOLD }

    public record Address(String zipCode, String city, boolean primary) {}
}
เอาต์พุต (JSON)
{
  "memberId": 0,
  "nick_name": "",
  "grade": "SILVER",
  "birthDate": "1970-01-01",
  "addresses": [
    {
      "zipCode": "",
      "city": "",
      "primary": false
    }
  ]
}

password ถูกตัดออกด้วย @JsonIgnoreProperties({"password"}) ระดับคลาส และ serialVersionUID ที่เป็น static final ไม่ปรากฏเลย ค่าเริ่มต้น Grade.SILVER ถูกอ่านมาใช้ grade จึงเป็น "SILVER" ไม่ใช่ค่าคงที่ตัวแรกของ enum ส่วน record Address ที่ซ้อนอยู่ถูกขยายเป็นอาร์เรย์ของออบเจ็กต์

ฟีเจอร์ที่รองรับ

  • ชื่อฟิลด์กลายเป็นคีย์ และถูกแทนที่ด้วย @JsonProperty("x") หรือ @JsonProperty(value = "x")
  • สิ่งที่ถูกตัดออก: ฟิลด์ที่มี @JsonIgnore คีย์ที่ระบุใน @JsonIgnoreProperties({...}) ระดับคลาส และฟิลด์ static หรือ transient
  • รองรับ component ของ record ใน Java 16+ การประกาศ static class ที่ซ้อนอยู่ และฟิลด์ที่สืบทอดผ่าน extends (ฟิลด์ของ parent มาก่อน)
  • ฟิลด์ enum ได้ค่าคงที่ตัวแรกเป็นสตริง หรือค่าคงที่ที่ระบุใน initializer ของฟิลด์ และ @JsonProperty("x") บนค่าคงที่จะเปลี่ยนสตริงเป็น x
  • วันที่เป็นไปตามผลลัพธ์ Jackson ค่าเริ่มต้นของ Spring Boot: LocalDateTime → 1970-01-01T00:00:00, LocalDate → 1970-01-01, Instant/OffsetDateTime/ZonedDateTime → สตริง ISO ที่ลงท้ายด้วย Z, java.util.Date/Timestamp → 1970-01-01T00:00:00.000+00:00
  • wrapper ตัวเลขอย่าง BigDecimal และ Long เป็น 0, Optional<T> ถูกแกะออกเป็น T, byte[] เป็นสตริง Base64 ส่วน UUID และ ObjectId ของ MongoDB ได้ค่าที่รูปแบบถูกต้อง
  • List, Set และอาร์เรย์ได้สมาชิกตัวอย่างหนึ่งตัว map ที่มีคีย์เป็นตัวเลขอย่าง Map<Long, V> ใช้ "0" นอกนั้นใช้ "key"

กรณีการใช้งาน

เติมตัวอย่างใน springdoc / Swagger

ค่า example ที่เขียนเองจะคลาดเคลื่อนทุกครั้งที่เพิ่มฟิลด์ใน DTO ให้สร้าง JSON จากซอร์ส DTO แล้วค่อยปรับค่าจากตรงนั้น จะไม่มีคีย์ที่ขาดหรือสะกดผิด

request body สำหรับเทสต์ MockMvc หรือ RestAssured

สร้าง JSON ของ request จาก DTO ที่เป็น @RequestBody โดยตรง แล้ววางลงใน text block (""") ในเทสต์ คีย์ที่เปลี่ยนชื่อด้วย @JsonProperty ถูกใช้แล้ว ตรงกับการ binding จริง

แชร์รูปร่างของ response ให้ frontend

นักพัฒนา frontend ที่ไม่ได้อ่านโค้ด backend จะได้โครงสร้าง JSON ของ endpoint ไปตรง ๆ ไม่ต้องมาตีความคลาส Java เอง

ข้อควรระวังและข้อจำกัด

  • initializer ของฟิลด์จะถูกใช้เมื่อเป็น literal (= "guest", = 100, = true) หรือค่าคงที่ของ enum (= Grade.SILVER) อย่างอื่นเช่น new ArrayList<>() หรือการเรียกเมธอดจะใช้ค่าตัวอย่างตามไทป์แทน
  • getter ที่ไม่มีฟิลด์คู่กัน เช่น getFullName() หรือ boolean isVip() ถูกเพิ่มเป็นพร็อพเพอร์ตีแบบเดียวกับที่ Jackson ทำ โดยเคารพ @JsonIgnore/@JsonProperty บน getter นั้น ในทางกลับกัน ฟิลด์ private ที่ไม่มี getter ถือว่ามองเห็นได้ (เหมือนใช้ Lombok @Getter/@Data)
  • กฎการตั้งชื่อแบบ global (@JsonNaming(SnakeCaseStrategy.class), spring.jackson.property-naming-strategy) และรูปแบบวันที่ของ @JsonFormat จะไม่ถูกนำมาใช้
  • เมธอด @JsonValue บน enum ไม่ถูกประมวลผล enum แบบนั้นจึงยังแสดงเป็นชื่อค่าคงที่ (หรือชื่อจาก @JsonProperty)
  • ฟิลด์ Page<T>/Slice<T> ของ Spring Data ถูกทำให้ง่ายเป็นอาร์เรย์ของสมาชิก ส่วนการ serialize Page จริงจะเป็นออบเจ็กต์ที่มี content, pageable และอื่น ๆ

คำถามที่พบบ่อย

ใช้ได้ไหมถ้า accessor ถูกสร้างโดย Lombok @Data หรือ @Getter?

ได้ คีย์ถูกสร้างจากฟิลด์ที่ประกาศไว้ getter และ setter ที่ Lombok สร้างตอนคอมไพล์จึงไม่จำเป็นต้องอยู่ในซอร์ส

ทำไม LocalDateTime เป็นสตริง ไม่ใช่อาร์เรย์ตัวเลข?

Spring Boot ลงทะเบียน jackson-datatype-jsr310 และปิด WRITE_DATES_AS_TIMESTAMPS ไว้เป็นค่าเริ่มต้น จึงได้สตริง ISO และตัวอย่างก็ทำตามค่าเริ่มต้นนั้น ถ้าใช้ ObjectMapper ของ Jackson เปล่า ๆ อาจได้อาร์เรย์อย่าง [1970,1,1,0,0] แทน

วาง JPA entity ได้ไหม?

entity มีโครงสร้างฟิลด์แบบเดียวกัน จึงพาร์สได้ปกติ ความสัมพันธ์สองทางอย่าง @OneToMany จะวนไม่จบ จึงถูกขยายหนึ่งครั้งแล้วตัดด้วย null หรืออาร์เรย์ว่าง และยังมีหน้า Spring Boot JPA → JSON โดยเฉพาะด้วย

ถ้า @JsonIgnore อยู่บน setter หรือบน getter ของฟิลด์ที่มีอยู่แล้วล่ะ?

annotation บนการประกาศฟิลด์มีผลเสมอ ส่วน annotation บน getter มีผลเฉพาะเมื่อไม่มีฟิลด์ชื่อนั้น @JsonIgnore บน setter หรือบน getter ของฟิลด์ที่ประกาศไว้จะไม่ถูกใช้ ให้ย้ายไปไว้ที่ฟิลด์เพื่อดูผล