Update version to 1.11.0

devslm · devslm · commit 37d7bf64c038 · 2023-08-02T13:08:37.000+02:00
Add error meta field for meta object containing non-standard meta-information about the error
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.11.0] - 2023-08-02
+### Added:
+  - Error meta field for meta object containing non-standard meta-information about the error
+
 ## [1.10.1] - 2023-06-17
 ### Fixed:
   - Missing **@NoArgsConstructor** annotation on **Meta** class for proper jackson response deserialization
diff --git a/README.md b/README.md
@@ -506,6 +506,58 @@ public class Test {
 }
 ```
 
+Example response with error with meta field (data is empty so we use ```Void```class as generic parameter):
+```java
+// Pseudo code
+public class Test {
+    public Response<Void> main() {
+        final ErrorMetaDto errorMeta = new ErrorMetaDto(
+            UUID.randomUUID(),
+            "Test meta value",
+            Set.of(
+                "Value 1",
+                "Value 2"
+            )
+        );
+        return Response.<Void, Void>builder()
+            .error(
+                HttpStatus.BAD_REQUEST,
+                "20045",
+                "Some errors occurred!",
+                errorMeta
+            ).build();
+    }
+}
+```
+```json
+{
+    "errors": [
+        {
+            "status": 400,
+            "code": "20045",
+            "detail": "Some errors occurred!",
+            "meta": {
+                "id": UUID,
+                "value": "Test meta value",
+                "codes": [
+                    "Value 1",
+                    "Value 2"
+                ]
+            }
+        }
+    ],
+    "meta": {
+        "api": {
+            "version": "1"
+        },
+        "page": {
+            "maxSize": 25,
+            "total": 0
+        }
+    }
+}
+```
+
 Example response with error with links (data is empty, so we use ```Void``` class as generic parameter):
 ```java
 // Pseudo code
diff --git a/pom.xml b/pom.xml
@@ -4,7 +4,7 @@
 	<modelVersion>4.0.0</modelVersion>
 	<groupId>com.slm-dev</groupId>
 	<artifactId>jsonapi-simple</artifactId>
-	<version>1.10.1</version>
+	<version>1.11.0</version>
 	<name>jsonapi-simple</name>
 	<description>Simple implementation of the JSON:API specification</description>
 	<url>https://slm-dev.com/jsonapi-simple/</url>
diff --git a/src/main/java/com/slmdev/jsonapi/simple/response/Error.java b/src/main/java/com/slmdev/jsonapi/simple/response/Error.java
@@ -20,7 +20,10 @@ public class Error {
     private String detail;
     @ApiModelProperty(value = "Parameter name only for validation errors")
     private Source source;
+    @ApiModelProperty(value = "Links object can be used to represent links")
     private ErrorLink links;
+    @ApiModelProperty(value = "Meta object containing non-standard meta-information about the error")
+    private Object meta;
 
     @Getter
     @ToString
@@ -29,6 +32,7 @@ public class Error {
     @Accessors(chain = true)
     @JsonInclude(JsonInclude.Include.NON_NULL)
     public static class Source {
+        @ApiModelProperty(value = "Object containing references to the primary source of the error")
         private String parameter;
     }
 
@@ -45,4 +49,14 @@ public static class ErrorLink {
         @ApiModelProperty(value = "A link that identifies the type of error that this particular error is an instance of")
         private String type;
     }
+    @Getter
+    @ToString
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Accessors(chain = true)
+    @JsonInclude(JsonInclude.Include.NON_NULL)
+    public static class ErrorMeta {
+        private Object meta;
+    }
 }
diff --git a/src/main/java/com/slmdev/jsonapi/simple/response/Response.java b/src/main/java/com/slmdev/jsonapi/simple/response/Response.java
@@ -347,6 +347,7 @@ public ResponseBuilder<T, V> validationError(final @NonNull String errorValidati
                 "VALIDATION_ERROR",
                 detail,
                 errorValidationField,
+                null,
                 null
             );
         }
@@ -359,7 +360,7 @@ public ResponseBuilder<T, V> validationError(final @NonNull String errorValidati
          * @return self link
          */
         public ResponseBuilder<T, V> error(final HttpStatus status, final String detail) {
-            return error(status, null, detail, null, null);
+            return error(status, null, detail, null, null, null);
         }
 
         /**
@@ -371,7 +372,7 @@ public ResponseBuilder<T, V> error(final HttpStatus status, final String detail)
          * @return self link
          */
         public ResponseBuilder<T, V> error(final HttpStatus status, final String code, final String detail) {
-            return error(status, code, detail, null, null);
+            return error(status, code, detail, null, null, null);
         }
 
         /**
@@ -390,7 +391,7 @@ public ResponseBuilder<T, V> error(final HttpStatus status,
                                            final String code,
                                            final @NonNull String detail,
                                            final String errorValidationField) {
-            return error(status, code, detail, errorValidationField, null);
+            return error(status, code, detail, errorValidationField, null, null);
         }
 
         /**
@@ -409,7 +410,47 @@ public ResponseBuilder<T, V> error(final HttpStatus status,
                                            final String code,
                                            final @NonNull String detail,
                                            final Error.ErrorLink links) {
-            return error(status, code, detail, null, links);
+            return error(status, code, detail, null, links, null);
+        }
+
+        /**
+         * Create errors object.
+         *
+         * <p>We can invoke this method as many times as we need and
+         * result object will contain all errors we passed.
+         *
+         * @param status spring {@link HttpStatus} object
+         * @param code internal error code (if exists)
+         * @param detail detail information about error
+         * @param errorMeta field with meta info for the non-standard details about error
+         * @return self link
+         */
+        public ResponseBuilder<T, V> error(final HttpStatus status,
+                                           final String code,
+                                           final @NonNull String detail,
+                                           final Error.ErrorMeta errorMeta) {
+            return error(status, code, detail, null, null, errorMeta);
+        }
+
+        /**
+         * Create errors object.
+         *
+         * <p>We can invoke this method as many times as we need and
+         * result object will contain all errors we passed.
+         *
+         * @param status spring {@link HttpStatus} object
+         * @param code internal error code (if exists)
+         * @param detail detail information about error
+         * @param links field with links for the details about error
+         * @param errorMeta field with meta info for the non-standard details about error
+         * @return self link
+         */
+        public ResponseBuilder<T, V> error(final HttpStatus status,
+                                           final String code,
+                                           final @NonNull String detail,
+                                           final Error.ErrorLink links,
+                                           final Error.ErrorMeta errorMeta) {
+            return error(status, code, detail, null, links, errorMeta);
         }
 
         /**
@@ -423,13 +464,15 @@ public ResponseBuilder<T, V> error(final HttpStatus status,
          * @param detail detail information about error
          * @param errorValidationField field with failed validation
          * @param links field with links for the details about error
+         * @param errorMeta field with meta info for the non-standard details about error
          * @return self link
          */
         public ResponseBuilder<T, V> error(final HttpStatus status,
                                            final String code,
                                            final @NonNull String detail,
                                            final String errorValidationField,
-                                           final Error.ErrorLink links) {
+                                           final Error.ErrorLink links,
+                                           final Error.ErrorMeta errorMeta) {
             if (this.errors == null) {
                 this.errors = new ArrayList<>();
             }
@@ -438,8 +481,10 @@ public ResponseBuilder<T, V> error(final HttpStatus status,
             if (StringUtils.hasText(errorValidationField)) {
                 errorSource = new Error.Source(errorValidationField);
             }
+            final Object errorMetaData = (errorMeta != null ? errorMeta.getMeta() : null);
+
             this.errors.add(
-                new Error(status.value(), code, detail, errorSource, links)
+                new Error(status.value(), code, detail, errorSource, links, errorMetaData)
             );
             this.dataList = null;
             this.dataObject = null;
diff --git a/src/test/java/com/slmdev/jsonapi/simple/response/BaseTest.java b/src/test/java/com/slmdev/jsonapi/simple/response/BaseTest.java
@@ -3,13 +3,17 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.json.JsonMapper;
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
 import lombok.NonNull;
 import org.springframework.http.HttpStatus;
 
 import java.time.LocalDateTime;
 import java.time.ZoneOffset;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.UUID;
 
 import static org.hamcrest.MatcherAssert.assertThat;
@@ -56,6 +60,14 @@ protected void assertResponseErrorCode(final @NonNull Response<?> response) {
         assertThat(response.getErrors().get(0).getCode(), is(ERROR_CODE));
     }
 
+    protected void assertResponseErrorMeta(final @NonNull Response<?> response, final @NonNull ErrorMetaDto requiredErrorMeta) {
+        final ErrorMetaDto errorMeta = objectMapper.convertValue(response.getErrors().get(0).getMeta(), ErrorMetaDto.class);
+
+        assertThat(errorMeta.getId(), is(requiredErrorMeta.getId()));
+        assertThat(errorMeta.getValue(), is(requiredErrorMeta.getValue()));
+        assertThat(errorMeta.getCodes().size(), is(2));
+    }
+
     protected void assertErrorResponse(final @NonNull Response<?> response) {
         assertThat(response.getData(), nullValue());
 
@@ -91,4 +103,24 @@ protected void assertThatAttributesIdFieldIsPresentInObject(final @NonNull Objec
 
         assertThat(idAttributeField, notNullValue());
     }
+
+    protected ErrorMetaDto buildTestErrorMeta() {
+        return new ErrorMetaDto(
+            UUID.randomUUID(),
+            "Test meta value",
+            Set.of(
+                "Value 1",
+                "Value 2"
+            )
+        );
+    }
+
+    @Data
+    @AllArgsConstructor
+    @NoArgsConstructor
+    protected static class ErrorMetaDto {
+        private UUID id;
+        private String value;
+        private Set<String> codes;
+    }
 }
diff --git a/src/test/java/com/slmdev/jsonapi/simple/response/ResponseDeserializationTest.java b/src/test/java/com/slmdev/jsonapi/simple/response/ResponseDeserializationTest.java
@@ -92,5 +92,23 @@ public void shouldDeserializeResponseWithErrorWithData() throws Exception {
         final Response<Data<TestDto>> deserealizedResponse = objectMapper.readValue(json, objectMapper.getTypeFactory().constructParametricType(Response.class, dataType));
 
         assertErrorResponse(deserealizedResponse);
+
+        assertThat(deserealizedResponse.getErrors().get(0).getMeta(), nullValue());
+    }
+
+    @Test
+    public void shouldDeserializeResponseWithErrorWithMetaAndWithData() throws Exception {
+        final ErrorMetaDto errorMeta = buildTestErrorMeta();
+        final Response<Data<TestDto>> response = Response.<Data<TestDto>, TestDto>builder()
+            .data(buildTestDto1())
+            .error(HttpStatus.BAD_REQUEST, ERROR_CODE, ERROR_DESCRIPTION, new Error.ErrorMeta(errorMeta))
+            .build();
+
+        final String json = objectMapper.writeValueAsString(response);
+        final JavaType dataType = objectMapper.getTypeFactory().constructParametricType(Data.class, TestDto.class);
+        final Response<Data<TestDto>> deserealizedResponse = objectMapper.readValue(json, objectMapper.getTypeFactory().constructParametricType(Response.class, dataType));
+
+        assertErrorResponse(deserealizedResponse);
+        assertResponseErrorMeta(deserealizedResponse, errorMeta);
     }
 }
diff --git a/src/test/java/com/slmdev/jsonapi/simple/response/ResponseTest.java b/src/test/java/com/slmdev/jsonapi/simple/response/ResponseTest.java
@@ -206,7 +206,7 @@ public void shouldReturnResponseWithValidationErrorWithEmptyData() {
 	}
 
 	@Test
-	public void shouldReturnResponseWithErrorWithLinkAndWith() {
+	public void shouldReturnResponseWithErrorWithLinkAndWithEmptyData() {
 		final Error.ErrorLink errorLink = Error.ErrorLink
 			.builder()
 			.about("https://example.org/docs/" + ERROR_CODE)
@@ -221,6 +221,19 @@ public void shouldReturnResponseWithErrorWithLinkAndWith() {
 		assertThat(response.getErrors().get(0).getLinks().getAbout(), is(errorLink.getAbout()));
 	}
 
+	@Test
+	public void shouldReturnResponseWithErrorCodeAndMetaAndWithData() {
+		final ErrorMetaDto errorMeta = buildTestErrorMeta();
+		final Response<Data<TestDto>> response = Response.<Data<TestDto>, TestDto>builder()
+			.data(buildTestDto1())
+			.error(HttpStatus.BAD_REQUEST, ERROR_CODE, ERROR_DESCRIPTION, new Error.ErrorMeta(errorMeta))
+			.build();
+
+		assertErrorResponse(response);
+		assertResponseErrorCode(response);
+		assertResponseErrorMeta(response, errorMeta);
+	}
+
 	@Test
 	public void shouldReturnResponseWithEmptyDataAndChangedMetaVersion() {
 		final Response<Void> response = Response.<Void, Void>builder()
