Documentation: microservices (#39) from doc(backend)/add-javadoc

Author: swyth-dev

backend/discovery-service/src/main/java/com/swyth/discoveryservice/DiscoveryServiceApplication.java

@@ -4,6 +4,17 @@
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.cloud.netflix.eureka.server.EnableEurekaServer;
 
+/**
+ * DiscoveryServiceApplication is the entry point for the Discovery Service application.
+ * This application acts as a Eureka Server for service discovery, allowing microservices
+ * to register themselves and discover other registered services.
+ *
+ * This class is annotated with:
+ * - @SpringBootApplication: Indicates a Spring Boot application.
+ * - @EnableEurekaServer: Activates the Netflix Eureka Server for service discovery capabilities.
+ *
+ * The main method initializes and runs the Spring Boot application.
+ */
 @SpringBootApplication
 @EnableEurekaServer
 public class DiscoveryServiceApplication {

backend/emergency-service/pom.xml

@@ -33,6 +33,12 @@
 		<sonar.host.url>https://sonarcloud.io</sonar.host.url>
 	</properties>
 	<dependencies>
+		<!-- https://mvnrepository.com/artifact/org.apache.maven.plugins/maven-javadoc-plugin -->
+		<dependency>
+			<groupId>org.apache.maven.plugins</groupId>
+			<artifactId>maven-javadoc-plugin</artifactId>
+			<version>3.11.2</version>
+		</dependency>
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-data-jpa</artifactId>

backend/emergency-service/src/main/java/com/swyth/emergencyservice/EmergencyServiceApplication.java

@@ -5,6 +5,19 @@
 import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
 import org.springframework.cloud.openfeign.EnableFeignClients;
 
+/**
+ * The EmergencyServiceApplication class serves as the entry point for the Emergency Service
+ * application. It configures the Spring Boot application as a discovery client
+ * and enables Feign clients for declarative REST client functionality.
+ *
+ * Annotations:
+ * - @SpringBootApplication: Marks this as a Spring Boot application.
+ * - @EnableFeignClients: Enables the detection of Feign clients in the application.
+ * - @EnableDiscoveryClient: Configures the application to register itself as a discovery client
+ *   in a service registry, allowing it to interact with other services.
+ *
+ * The main method initializes and runs the Spring Boot application.
+ */
 @SpringBootApplication
 @EnableFeignClients
 @EnableDiscoveryClient

backend/emergency-service/src/main/java/com/swyth/emergencyservice/config/CustomErrorDecoder.java

@@ -10,6 +10,12 @@
 import java.io.InputStream;
 import java.util.Map;
 
+/**
+ * CustomErrorDecoder is an implementation of the ErrorDecoder interface
+ * used to decode and handle HTTP error responses in a Feign client.
+ * It parses the error details from the response body and maps specific
+ * HTTP status codes to custom exceptions.
+ */
 public class CustomErrorDecoder implements ErrorDecoder {
 
     // Jackson ObjectMapper to parse JSON

backend/emergency-service/src/main/java/com/swyth/emergencyservice/config/FeignConfig.java

@@ -9,6 +9,14 @@
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
+/**
+ * FeignConfig class provides the configuration for Feign clients in the application.
+ *
+ * This class customizes the Feign client by registering beans for request and response
+ * encoding/decoding and error handling. The configurations ensure that Feign clients
+ * can seamlessly integrate with the application's data format and handle errors
+ * appropriately.
+ */
 @Configuration
 public class FeignConfig {
 

backend/emergency-service/src/main/java/com/swyth/emergencyservice/config/FeignReactiveConfig.java

@@ -6,6 +6,13 @@
 import reactor.core.scheduler.Schedulers;
 import java.util.concurrent.Executors;
 
+/**
+ * Configuration class for setting up reactive Feign components.
+ *
+ * This class defines custom configurations required for reactive Feign,
+ * including a scheduler for managing blocking operations in a reactive context, that fixed
+ * a blocking single thread operation error.
+ */
 @Configuration
 public class FeignReactiveConfig {
 

backend/emergency-service/src/main/java/com/swyth/emergencyservice/controller/BedReservationController.java

@@ -10,13 +10,40 @@
 import org.springframework.web.bind.annotation.*;
 import reactor.core.publisher.Mono;
 
+/**
+ * Rest Controller handling bed reservation-related operations.
+ *
+ * The BedReservationController manages endpoints for creating bed reservations
+ * and retrieving information about existing reservations. It interacts with
+ * the {@link BedReservationService} to perform the necessary business logic and
+ * return results as HTTP responses.
+ *
+ * Endpoints:
+ * - GET /v1/bed-reservations/{id}: Retrieves details of a bed reservation by its unique ID.
+ * - POST /v1/bed-reservations: Creates a new bed reservation with the provided details.
+ *
+ * Dependencies:
+ * - {@link BedReservationService}: The service layer responsible for bed reservation operations.
+ *
+ * Validation and Exceptions:
+ * - Handles input validation for creating bed reservations using {@link BedReservationDTO}.
+ * - Throws {@link BedUnavailableException} if no bed is available for the requested criteria.
+ */
 @Controller
 @RestController
 @RequestMapping("/v1/bed-reservations")
-//@CrossOrigin(origins = "*", allowedHeaders = "*") //TODO: don't let it like that in Production env
 public class BedReservationController {
     private final BedReservationService bedReservationService;
 
+    /**
+     * Constructs the BedReservationController with a BedReservationService dependency.
+     *
+     * This constructor initializes the controller with the specified service, which provides
+     * the business logic for handling bed reservation-related operations such as creation
+     * and retrieval of bed reservations.
+     *
+     * @param bedReservationService the service responsible for managing bed reservation logic
+     */
     public BedReservationController(BedReservationService bedReservationService) {
         this.bedReservationService = bedReservationService;
     }

backend/emergency-service/src/main/java/com/swyth/emergencyservice/dto/BedReservationDTO.java

@@ -5,7 +5,16 @@
 import jakarta.validation.constraints.Pattern;
 import lombok.Data;
 
-// TODO: refactor to bed reservation Request/Payload
+/**
+ * Data Transfer Object for handling bed reservation requests.
+ *
+ * This class encapsulates the details required to create a bed reservation for a specific hospital
+ * and medical specialization. It includes information about the hospital, medical specialization,
+ * and the personal details of the individual making the reservation.
+ *
+ * Validation annotations are included for ensuring the integrity and correctness
+ * of the data provided in the request.
+ */
 @Data
 public class BedReservationDTO {
 

backend/emergency-service/src/main/java/com/swyth/emergencyservice/dto/BedReservationResponseDTO.java

@@ -6,7 +6,24 @@
 import lombok.AllArgsConstructor;
 import lombok.Data;
 
-// TODO : Refactor to BedReservation
+/**
+ * Data Transfer Object representing a response for a bed reservation.
+ *
+ * This class is used to encapsulate the response details of a bed reservation,
+ * including the reservation's ID, the associated hospital and medical specialization IDs,
+ * as well as the personal and contact details of the individual for whom the reservation is made.
+ * This DTO is intended for use in response payloads within applications, enabling
+ * a clear separation between internal domain models and API responses.
+ *
+ * Fields:
+ * - id: The unique identifier for the bed reservation.
+ * - hospitalId: The identifier of the hospital where the reservation is made.
+ * - medicalSpecializationId: The identifier of the medical specialization associated with the reservation.
+ * - reservationFirstName: The first name of the person for whom the reservation is made.
+ * - reservationLastName: The last name of the person for whom the reservation is made.
+ * - reservationEmail: The email address of the person for whom the reservation is made.
+ * - reservationPhoneNumber: The phone number of the person for whom the reservation is made.
+ */
 @Data
 @AllArgsConstructor
 public class BedReservationResponseDTO {

backend/emergency-service/src/main/java/com/swyth/emergencyservice/dto/BedReservationResponseDtoMapper.java

@@ -2,11 +2,21 @@
 
 import com.swyth.emergencyservice.entity.BedReservation;
 
+/**
+ * This class provides mapping functionality to convert a {@code BedReservation} entity
+ * into a {@code BedReservationResponseDTO}.
+ *
+ * The purpose of the {@code BedReservationResponseDtoMapper} is to extract
+ * relevant fields from the {@code BedReservation} entity and package them
+ * into a data transfer object ({@code BedReservationResponseDTO})
+ * for use in external layers such as APIs or client responses.
+ *
+ * The mapper ensures consistency and reduces the complexity of
+ * transforming domain objects into DTOs by providing a dedicated method
+ * for the transformation process.
+ */
 public class BedReservationResponseDtoMapper {
 
-    public BedReservationResponseDtoMapper() {
-    }
-
     public static BedReservationResponseDTO convertToDTO(BedReservation reservation) {
         return new BedReservationResponseDTO(
                 reservation.getId(),