Added project documentation.

Author: ksbrwsk

CHANGELOG.md

@@ -4,4 +4,4 @@ Release v1.1.1
 
 **Full Changelog**: https://github.com/ksbrwsk/reactive-people-postgresql/compare/1.0.2...v1.1.1
 
-## What’s Changed
+

src/main/java/de/ksbrwsk/people/Constants.java

@@ -1,5 +1,11 @@
 package de.ksbrwsk.people;
 
+/**
+ * This class contains constants that are used throughout the application.
+ */
 public class Constants {
+    /**
+     * The base API endpoint for all people-related operations.
+     */
     public static final String API = "/api/people";
-}
+}

src/main/java/de/ksbrwsk/people/PeopleApplication.java

@@ -6,6 +6,12 @@
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.data.r2dbc.repository.config.EnableR2dbcRepositories;
 
+/**
+ * This is the main class for the PeopleApplication.
+ * It uses the @SpringBootApplication annotation to enable auto-configuration and component scanning.
+ * It also uses the @EnableR2dbcRepositories annotation to enable the creation of reactive repositories.
+ * The @OpenAPIDefinition annotation is used to provide metadata for the OpenAPI documentation.
+ */
 @SpringBootApplication
 @EnableR2dbcRepositories
 @OpenAPIDefinition(info = @Info(
@@ -15,8 +21,11 @@
 ))
 public class PeopleApplication {
 
+    /**
+     * The main method that starts the application.
+     * @param args The command line arguments.
+     */
     public static void main(String[] args) {
         SpringApplication.run(PeopleApplication.class, args);
     }
-
-}
+}

src/main/java/de/ksbrwsk/people/Person.java

@@ -1,27 +1,43 @@
 package de.ksbrwsk.people;
 
 import io.swagger.v3.oas.annotations.media.Schema;
-import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.Size;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 import org.springframework.data.annotation.Id;
 
+/**
+ * This class represents a Person entity.
+ * It includes validation and API documentation annotations.
+ */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
 public class Person {
+    /**
+     * The unique identifier of the person.
+     * It is automatically generated.
+     */
     @Id
     @Schema(name = "id", description = "The person's id")
     private Long id;
 
-    @NotNull
+    /**
+     * The name of the person.
+     * It cannot be blank and its size must be between 1 and 10 characters.
+     */
+    @NotBlank
     @Size(min = 1, max = 10)
     @Schema(minLength = 1, maxLength = 10, nullable = false, name = "name", description = "The person's name")
     private String name;
 
+    /**
+     * Constructor that sets the name of the person.
+     * @param name The name of the person.
+     */
     public Person(String name) {
         this.name = name;
     }
-}
+}

src/main/java/de/ksbrwsk/people/PersonHandler.java

@@ -23,18 +23,32 @@
 import static org.springframework.web.reactive.function.BodyInserters.fromValue;
 import static org.springframework.web.reactive.function.server.ServerResponse.*;
 
+/**
+ * This class is responsible for handling HTTP requests related to the Person entity.
+ * It includes methods for CRUD operations and finding a person by name.
+ */
 @Component
 @RequiredArgsConstructor
 @Slf4j
 public class PersonHandler {
     private final PersonRepository personRepository;
     private final Validator validator;
 
+    /**
+     * Handles a request to get all persons.
+     * @param serverRequest The incoming server request.
+     * @return A ServerResponse with the list of all persons.
+     */
     public Mono<ServerResponse> handleFindAll(ServerRequest serverRequest) {
         return ok()
                 .body(this.personRepository.findAll(), Person.class);
     }
 
+    /**
+     * Handles a request to get a person by id.
+     * @param serverRequest The incoming server request.
+     * @return A ServerResponse with the person found or a 404 status if not found.
+     */
     public Mono<ServerResponse> handleFindById(ServerRequest serverRequest) {
         var id = Long.parseLong(serverRequest.pathVariable("id"));
         return this.personRepository.findById(id)
@@ -43,6 +57,11 @@ public Mono<ServerResponse> handleFindById(ServerRequest serverRequest) {
                 .switchIfEmpty(notFound().build());
     }
 
+    /**
+     * Handles a request to get the first person found by name.
+     * @param serverRequest The incoming server request.
+     * @return A ServerResponse with the person found or a 404 status if not found.
+     */
     public Mono<ServerResponse> handleFindFirstByName(ServerRequest serverRequest) {
         log.info("Handle request {} {}", serverRequest.method(), serverRequest.path());
         var name = serverRequest.pathVariable("name");
@@ -53,6 +72,11 @@ public Mono<ServerResponse> handleFindFirstByName(ServerRequest serverRequest) {
                 .switchIfEmpty(notFound);
     }
 
+    /**
+     * Handles a request to delete a person by id.
+     * @param serverRequest The incoming server request.
+     * @return A ServerResponse with a success message or a 404 status if not found.
+     */
     public Mono<ServerResponse> handleDeleteById(ServerRequest serverRequest) {
         var id = Long.parseLong(serverRequest.pathVariable("id"));
         return this.personRepository.findById(id)
@@ -64,6 +88,11 @@ public Mono<ServerResponse> handleDeleteById(ServerRequest serverRequest) {
                         .bodyValue(msg));
     }
 
+    /**
+     * Handles a request to create a new person.
+     * @param serverRequest The incoming server request.
+     * @return A ServerResponse with the created person or a 400 status if the request body is invalid.
+     */
     public Mono<ServerResponse> handleCreate(ServerRequest serverRequest) {
         return serverRequest.bodyToMono(Person.class)
                 .switchIfEmpty(Mono.error(new ServerWebInputException("person must not be null")))
@@ -74,6 +103,11 @@ public Mono<ServerResponse> handleCreate(ServerRequest serverRequest) {
                                 .bodyValue(person));
     }
 
+    /**
+     * Handles a request to update a person by id.
+     * @param serverRequest The incoming server request.
+     * @return A ServerResponse with the updated person or a 404 status if not found.
+     */
     public Mono<ServerResponse> handleUpdate(ServerRequest serverRequest) {
         var id = Long.parseLong(serverRequest.pathVariable("id"));
         final Mono<Person> update = serverRequest.bodyToMono(Person.class)
@@ -90,6 +124,11 @@ public Mono<ServerResponse> handleUpdate(ServerRequest serverRequest) {
                 .switchIfEmpty(notFound().build());
     }
 
+    /**
+     * Validates a person using the Validator.
+     * @param person The person to validate.
+     * @throws ServerWebInputException If the person is not valid.
+     */
     private void validate(Person person) {
         Set<ConstraintViolation<Person>> violations = this.validator.validate(person);
         if (!violations.isEmpty()) {
@@ -101,9 +140,14 @@ private void validate(Person person) {
         }
     }
 
+    /**
+     * Formats a validation error.
+     * @param personConstraintViolation The validation error.
+     * @return A string representation of the validation error.
+     */
     private String formatError(ConstraintViolation<Person> personConstraintViolation) {
         String field = StringUtils.capitalize(personConstraintViolation.getPropertyPath().toString());
         String error = personConstraintViolation.getMessage();
         return String.format("%s - %s", field, error);
     }
-}
+}

src/main/java/de/ksbrwsk/people/PersonRepository.java

@@ -3,8 +3,21 @@
 import org.springframework.data.repository.reactive.ReactiveCrudRepository;
 import reactor.core.publisher.Mono;
 
+/**
+ * This interface represents a repository for the Person entity.
+ * It extends the ReactiveCrudRepository interface provided by Spring Data.
+ */
 public interface PersonRepository extends ReactiveCrudRepository<Person, Long> {
+    /**
+     * This method returns the first Person found with the given name.
+     * @param name The name of the Person to search for.
+     * @return A Mono that emits the found Person or completes without emitting any items if no Person is found.
+     */
     Mono<Person> findFirstByName(String name);
 
+    /**
+     * This method returns the Person with the lowest id.
+     * @return A Mono that emits the found Person or completes without emitting any items if no Person is found.
+     */
     Mono<Person> findTopByOrderByIdAsc();
-}
+}

src/main/java/de/ksbrwsk/people/PersonRouter.java

@@ -22,8 +22,19 @@
 import static org.springframework.web.reactive.function.server.RouterFunctions.nest;
 import static org.springframework.web.reactive.function.server.RouterFunctions.route;
 
+/**
+ * This class is responsible for routing HTTP requests to the appropriate handler methods.
+ * It uses Spring's functional routing style with RouterFunctions and RequestPredicates.
+ */
 @Configuration
 public class PersonRouter {
+    /**
+     * This method defines the routes for the Person API.
+     * It uses the @RouterOperations annotation to provide OpenAPI documentation for each route.
+     *
+     * @param personHandler The handler class that contains the methods to handle the requests.
+     * @return A RouterFunction that routes requests to the appropriate handler methods.
+     */
     @Bean
     @RouterOperations(
             {

src/test/java/de/ksbrwsk/people/PersonTest.java

@@ -7,11 +7,9 @@
 import org.junit.jupiter.params.provider.ValueSource;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.context.SpringBootTest;
-import org.springframework.boot.test.context.TestConfiguration;
 import org.springframework.test.context.TestPropertySource;
 
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.assertj.core.api.Assertions.assertThat;
 
 @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
 @TestPropertySource(properties = {"spring.autoconfigure.exclude=" +
@@ -23,18 +21,25 @@ class PersonTest {
     @Test
     void should_create_person() {
         Person person = new Person(1L, "Name");
-        assertEquals(person.getId(), 1L);
-        assertEquals(person.getName(), "Name");
+        assertThat(person.getId()).isEqualTo(1L);
+        assertThat(person.getName()).isEqualTo("Name");
     }
 
+    @ParameterizedTest
+    @ValueSource(strings = {"N", "Name", "0123456789"})
+    void should_create_valid_person(String name) {
+        Person person = new Person(name);
+        var violations = this.validator.validate(person);
+        assertThat(violations).isEmpty();
+    }
 
     @ParameterizedTest
     @NullAndEmptySource
     @ValueSource(strings = {"01234567890"})
-    void notValid(String name) {
+    void should_create_invalid_person(String name) {
         Person person = new Person(name);
         var violations = this.validator.validate(person);
-        assertFalse(violations.isEmpty());
+        assertThat(violations).isNotEmpty();
         violations.forEach(System.out::println);
     }
 }