chore: clean codes

Author: hantsy

docs/problem-detail.md

@@ -1,13 +1,14 @@
 # An Introduction to Spring ProblemDetails Support
-When building REST API backend applications, developers often create custom wrappers, such as `ApiResult` or `ErrorResponse`, to standardize response formats within their projects. However, these solutions are not portable across different systems. As a developer, I find it frustrating to handle various response formats when integrating with other third-party APIs.
 
-[Spring HATEOAS](https://spring.io/projects/spring-hateoas) adopts the [VndError draft proposal](https://github.com/blongden/vnd.error) to represent REST response messages. While Spring HATEOAS is mainly focused on building hypermedia-driven APIs, it also helps applications reach the Richardson Maturity Model Level 3.
+When building REST API backends, developers often create custom wrappers, such as `ApiResult` or `ErrorResponse` to standardize response formats within their projects. However, these solutions are rarely portable across different systems. As a developer, I find it frustrating to handle various response formats when integrating with third-party APIs.
 
-Another widely accepted format is Problem Details, standardized by the IETF as [RFC9457](https://www.rfc-editor.org/rfc/rfc9457.html). Problem Details for HTTP APIs (also known as Problem Details) defines a consistent, machine-readable structure for representing error conditions in HTTP responses. This specification enables clients to interpret and handle errors uniformly, simplifying integration and improving interoperability across different systems.
+[Spring HATEOAS](https://spring.io/projects/spring-hateoas) adopts the [VndError draft proposal](https://github.com/blongden/vnd.error) to represent REST response messages. While Spring HATEOAS primarily focuses on building hypermedia-driven APIs, it also helps applications reach Level 3 of the Richardson Maturity Model.
 
-Building on these industry standards, Spring 6 has introduced native support for ProblemDetails, making it easier for developers to adopt this consistent error format in their applications.
+Another widely accepted format is Problem Details, standardized by the IETF as [RFC9457](https://www.rfc-editor.org/rfc/rfc9457.html). Problem Details for HTTP APIs defines a consistent, human being friendly and readable structure for representing error conditions in HTTP responses. This specification enables clients to interpret and handle errors uniformly, simplifying integration and improving interoperability across different systems.
 
-Let's take a closer look at the new [`ProblemDetail`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/ProblemDetail.html) class that was introduced in Spring 6, which is just a POJO and includes several fields defined by RFC 9457:
+Finally Spring 6 adds native support for ProblemDetails, making it easier for developers to adopt this consistent error format in their applications.
+
+Let’s take a closer look at the new [`ProblemDetail`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/ProblemDetail.html) class introduced in Spring 6. This POJO includes several fields defined by RFC 9457:
 
 * `type` – A URI identifying the problem type
 * `status` – The HTTP status code
@@ -18,7 +19,7 @@ Let's take a closer look at the new [`ProblemDetail`](https://docs.spring.io/spr
 
 The `ProblemDetail` class provides two convenient factory methods: `forStatus(HttpStatus status)` and `forStatusAndDetail(HttpStatusCode status, String detail)`, making it easy to create ProblemDetail objects.
 
-In a Spring WebMvc or WebFlux project, you can assemble error responses using `@ExceptionHandler` methods in a `@ControllerAdvice/@RestControllerAdvice` bean, update the method returns a `ResponseEntity<ProblemDetail>` or `ProblemDetail`.
+In a Spring WebMvc or WebFlux project, you can assemble error responses using `@ExceptionHandler` methods in a `@ControllerAdvice` or `@RestControllerAdvice` bean. These methods can return either a `ResponseEntity<ProblemDetail>` or a `ProblemDetail` directly:
 
 ```java
 @RestControllerAdvice
@@ -50,6 +51,33 @@ When an exception is handled, the response is rendered with the content type `ap
     "instance": "/api/posts/xxxx"
 }
 ```
+
+When using the Jackson library, custom properties added to the `properties` map are serialized as top-level JSON fields, thanks to the `ProblemDetailJacksonMixin`. For example, if you set custom properties via `setProperty("errors", obj)`:
+
+```java
+detail.setProperty("errors",
+    List.of(
+        Map.of("path", "title", "detail", "Cannot be empty")
+    )
+);
+```
+
+The resulting response will include the custom `errors` field at the top level:
+
+```json
+{
+    // ...
+    "status": 400,
+    "instance": "/api/posts/xxxx",
+    "errors": [
+        {
+            "path": "title",
+            "detail": "Cannot be empty"
+        }
+    ]
+}
+```
+
 You can explore the complete [sample code](https://github.com/hantsy/spring6-sandbox/tree/master/problem-details) on GitHub.
 
 To enable ProblemDetails support in a Spring Boot project, add the following properties to your *application.properties* file:
@@ -62,12 +90,12 @@ spring.mvc.problemdetails.enabled=true
 spring.webflux.problemdetails.enabled=true
 ```
 
-Once enabled, you can use ProblemDetails as demonstrated above. Additionally, Spring Boot's built-in error handling will also return errors in the ProblemDetails format.
+Once enabled, you can use ProblemDetails as demonstrated above. Additionally, Spring Boot’s built-in error handling will also return errors in the ProblemDetails format.
 
 Before the introduction of native support in Spring 6, developers who wanted to adopt the Problem Details format often turned to [Zalando Problem](https://github.com/zalando/problem). This library, along with its [Spring Web integration](https://github.com/zalando/problem-spring-web), provides comprehensive support for both WebMvc and WebFlux applications.
 
 > [!NOTE]
-> Zalando's Problem library and its Spring integration module offer more extensive integration with the Spring ecosystem than the current built-in support in Spring Boot. For instance, it can automatically handle security-related exceptions and Jakarta Validation errors, among other advanced features.
+> Zalando’s Problem library and its Spring integration module offer more extensive integration with the Spring ecosystem than the current built-in support in Spring Boot. For instance, it can automatically handle security-related exceptions and Jakarta Validation errors, among other advanced features.
 
 ---
 

problem-details/src/main/java/com/example/demo/web/RestExceptionHandler.java

@@ -8,6 +8,9 @@
 import org.springframework.web.bind.annotation.RestControllerAdvice;
 import org.springframework.web.reactive.result.method.annotation.ResponseEntityExceptionHandler;
 
+import java.util.List;
+import java.util.Map;
+
 @RestControllerAdvice
 public class RestExceptionHandler extends ResponseEntityExceptionHandler {
 
@@ -22,6 +25,12 @@ public ResponseEntity<ProblemDetail> handleNotFoundException(PostNotFoundExcepti
 
     @ExceptionHandler(IllegalArgumentException.class)
     public ProblemDetail handleIllegalArgumentException(IllegalArgumentException exception) {
-        return ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, exception.getMessage());
+        ProblemDetail detail = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, exception.getMessage());
+        detail.setProperty("errors",
+                List.of(
+                        Map.of("path", "title", "details", "Can not be empty")
+                )
+        );
+        return detail;
     }
 }