Merge pull request #34 from Rapter1990/development/add-java-doc

Add Java Doc

src/main/java/com/project/parkinglot/ParkinglotApplication.java

@@ -3,9 +3,17 @@
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 
+/**
+ * Main class named {@link ParkinglotApplication} to start the Parking Lot application.
+ */
 @SpringBootApplication
 public class ParkinglotApplication {
 
+	/**
+	 * Main method to start the Spring Boot application.
+	 *
+	 * @param args the command line arguments
+	 */
 	public static void main(String[] args) {
 		SpringApplication.run(ParkinglotApplication.class, args);
 	}

src/main/java/com/project/parkinglot/common/model/entity/BaseEntity.java

@@ -15,6 +15,11 @@
 
 import java.time.LocalDateTime;
 
+/**
+ * Base class named {@link BaseEntity} for all entities in the application. It provides common fields
+ * such as createdUser, createdAt, updatedUser, and updatedAt along with
+ * prePersist and preUpdate hooks to manage these fields automatically.
+ */
 @Getter
 @Setter
 @SuperBuilder

src/main/java/com/project/parkinglot/config/OpenApiConfig.java

@@ -7,6 +7,9 @@
 import io.swagger.v3.oas.annotations.info.Info;
 import io.swagger.v3.oas.annotations.security.SecurityScheme;
 
+/**
+ * Configuration class named {@link OpenApiConfig} for OpenAPI documentation.
+ */
 @OpenAPIDefinition(
         info = @Info(
                 contact = @Contact(

src/main/java/com/project/parkinglot/config/SecurityConfig.java

@@ -25,6 +25,9 @@
 
 import java.util.List;
 
+/**
+ * Configuration class named {@link SecurityConfig} for security settings.
+ */
 @Configuration
 @EnableWebSecurity
 @EnableMethodSecurity

src/main/java/com/project/parkinglot/controller/AuthController.java

@@ -17,6 +17,9 @@
 import org.springframework.http.HttpStatus;
 import org.springframework.web.bind.annotation.*;
 
+/**
+ * Controller class named {@link AuthController} for authentication operations.
+ */
 @RestController
 @RequestMapping("/api/v1/auth")
 @RequiredArgsConstructor
@@ -25,6 +28,12 @@ public class AuthController {
 
     private final AuthService authService;
 
+    /**
+     * Registers a new user.
+     *
+     * @param request The SignupRequest object containing user details.
+     * @return A CustomResponse containing a success message.
+     */
     @PostMapping("/register")
     @ResponseStatus(HttpStatus.CREATED)
     @Operation(summary = "Register a new user", description = "Registers a new user and returns a success message.",
@@ -37,6 +46,12 @@ public CustomResponse<String> register(@RequestBody SignupRequest request) {
         return CustomResponse.created(authService.register(request));
     }
 
+    /**
+     * Logs in a user and returns JWT tokens.
+     *
+     * @param request The LoginRequest object containing user credentials.
+     * @return A CustomResponse containing JWT tokens.
+     */
     @PostMapping("/login")
     @Operation(summary = "Login user", description = "Logs in a user and returns JWT tokens.",
             responses = {
@@ -48,6 +63,12 @@ public CustomResponse<JWTResponse> login(@RequestBody LoginRequest request) {
         return CustomResponse.ok(authService.login(request));
     }
 
+    /**
+     * Refreshes the JWT authentication token using a refresh token.
+     *
+     * @param request The TokenRefreshRequest object containing the refresh token.
+     * @return A CustomResponse containing the refreshed token.
+     */
     @PostMapping("/refreshtoken")
     @Operation(summary = "Refresh token", description = "Refreshes the JWT authentication token using a refresh token.",
             responses = {
@@ -59,6 +80,12 @@ public CustomResponse<TokenRefreshResponse> refreshToken(@RequestBody TokenRefre
         return CustomResponse.ok(authService.refreshToken(request));
     }
 
+    /**
+     * Logs out a user by invalidating the authentication token.
+     *
+     * @param token The JWT token to invalidate.
+     * @return A CustomResponse containing a success message.
+     */
     @PostMapping("/logout")
     @Operation(summary = "Logout user", description = "Logs out a user by invalidating the authentication token.",
             responses = {

src/main/java/com/project/parkinglot/controller/ParkController.java

@@ -19,6 +19,9 @@
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
+/**
+ * Controller class named {@link ParkController} for park management operations.
+ */
 @RestController
 @RequestMapping("/api/v1/parks")
 @RequiredArgsConstructor
@@ -28,6 +31,13 @@ public class ParkController {
 
     private final ParkService parkService;
 
+    /**
+     * Allows a driver to check in to a park, recording the time and location.
+     *
+     * @param userId               The ID of the user checking in.
+     * @param parkCheckInRequest   The ParkCheckInRequest containing check-in details.
+     * @return A CustomResponse containing the check-in response.
+     */
     @PostMapping("/userId/{userId}/check-in")
     @PreAuthorize("hasAuthority('ROLE_DRIVER')")
     @Operation(summary = "Check in to a park",
@@ -44,6 +54,13 @@ public CustomResponse<ParkCheckInResponse> checkIn(@PathVariable @UUID final Str
         return CustomResponse.ok(parkCheckInResponse);
     }
 
+    /**
+     * Allows a driver to check out from a park, recording the departure time.
+     *
+     * @param userId               The ID of the user checking out.
+     * @param parkCheckOutRequest  The ParkCheckOutRequest containing check-out details.
+     * @return A CustomResponse containing the check-out response.
+     */
     @PostMapping("/userId/{userId}/check-out")
     @PreAuthorize("hasAuthority('ROLE_DRIVER')")
     @Operation(summary = "Check out from a park",

src/main/java/com/project/parkinglot/controller/ParkingAreaController.java

@@ -26,6 +26,9 @@
 
 import java.time.LocalDate;
 
+/**
+ * Controller class named {@link ParkingAreaController} for managing parking areas.
+ */
 @RestController
 @RequestMapping("/api/v1/parking-area")
 @RequiredArgsConstructor
@@ -38,6 +41,12 @@ public class ParkingAreaController {
     private final ParkingAreaDeleteService parkingAreaDeleteService;
     private final ParkingAreaGetService parkingAreaGetService;
 
+    /**
+     * Creates a new parking area with the specified details.
+     *
+     * @param parkingAreaCreateRequest The details of the parking area to be created.
+     * @return A CustomResponse indicating the success of the operation.
+     */
     @PostMapping
     @PreAuthorize("hasAuthority('ROLE_ADMIN')")
     @Operation(summary = "Create a new parking area",
@@ -57,6 +66,12 @@ public CustomResponse<String> createParkingArea(@RequestBody @Valid final Parkin
 
     }
 
+    /**
+     * Retrieves details of a parking area by its ID.
+     *
+     * @param parkingAreaId The ID of the parking area.
+     * @return A CustomResponse containing the details of the parking area.
+     */
     @GetMapping("/{parkingAreaId}")
     @PreAuthorize("hasAuthority('ROLE_ADMIN')")
     @Operation(summary = "Get a parking area by ID",
@@ -74,6 +89,12 @@ public CustomResponse<ParkingArea> getParkingAreaById(@PathVariable("parkingArea
 
     }
 
+    /**
+     * Retrieves details of a parking area by its name.
+     *
+     * @param name The name of the parking area.
+     * @return A CustomResponse containing the details of the parking area.
+     */
     @GetMapping("/name/{name}")
     @PreAuthorize("hasAuthority('ROLE_ADMIN')")
     @Operation(summary = "Get a parking area by name",
@@ -91,6 +112,13 @@ public CustomResponse<ParkingArea> getParkingAreaByName(@PathVariable("name") @N
 
     }
 
+    /**
+     * Retrieves the daily income for a parking area on a specified date.
+     *
+     * @param date          The date for which the income is to be retrieved.
+     * @param parkingAreaId The ID of the parking area.
+     * @return A CustomResponse containing the daily income for the parking area.
+     */
     @GetMapping("/income")
     @PreAuthorize("hasAuthority('ROLE_ADMIN')")
     @Operation(summary = "Get daily income for a parking area",
@@ -109,6 +137,12 @@ public CustomResponse<ParkingAreaIncomeResponse> getDailyIncome(
         return CustomResponse.ok(dailyIncome);
     }
 
+    /**
+     * Deletes a parking area by its ID.
+     *
+     * @param parkingAreaId The ID of the parking area to be deleted.
+     * @return A CustomResponse indicating the success of the operation.
+     */
     @DeleteMapping("/{parkingAreaId}")
     @PreAuthorize("hasAuthority('ROLE_ADMIN')")
     @Operation(summary = "Delete a parking area by ID",
@@ -126,6 +160,13 @@ public CustomResponse<String> deleteParkingAreaById(@PathVariable("parkingAreaId
 
     }
 
+    /**
+     * Updates a parking area by its ID based on the provided data.
+     *
+     * @param parkingAreaId             The ID of the parking area to be updated.
+     * @param parkingAreaUpdateRequest The updated details of the parking area.
+     * @return A CustomResponse indicating the success of the operation.
+     */
     @PutMapping("/{parkingAreaId}")
     @PreAuthorize("hasAuthority('ROLE_ADMIN')")
     @Operation(summary = "Update a parking area by ID",

src/main/java/com/project/parkinglot/controller/UserController.java

@@ -18,6 +18,9 @@
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+/**
+ * Controller class named {@link UserController} for managing user information.
+ */
 @RestController
 @RequestMapping("/api/v1/users")
 @RequiredArgsConstructor
@@ -27,6 +30,12 @@ public class UserController {
 
     private final UserGetService userGetService;
 
+    /**
+     * Retrieves detailed information for a specific user by their ID.
+     *
+     * @param userId The ID of the user.
+     * @return A CustomResponse containing the user information.
+     */
     @GetMapping("/user/{user-id}")
     @PreAuthorize("hasAuthority('ROLE_DRIVER')")
     @Operation(summary = "Get user information by ID",
@@ -44,6 +53,12 @@ public CustomResponse<User> getUserInformationById(@PathVariable("user-id") @UUI
         return CustomResponse.ok(user);
     }
 
+    /**
+     * Retrieves detailed information for a specific admin by their ID.
+     *
+     * @param adminId The ID of the admin.
+     * @return A CustomResponse containing the admin information.
+     */
     @GetMapping("/admin/{admin-id}")
     @PreAuthorize("hasAuthority('ROLE_ADMIN')")
     @Operation(summary = "Get admin information by ID",

src/main/java/com/project/parkinglot/controller/VehicleController.java

@@ -19,6 +19,9 @@
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
+/**
+ * Controller class named {@link VehicleController} for managing vehicles.
+ */
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("api/v1/vehicles")
@@ -28,6 +31,13 @@ public class VehicleController {
 
     private final VehicleService vehicleService;
 
+    /**
+     * Assigns a vehicle based on the provided request to a specified user.
+     *
+     * @param userId         The ID of the user to whom the vehicle is to be assigned.
+     * @param vehicleRequest The details of the vehicle to be assigned.
+     * @return A CustomResponse indicating the success of the operation.
+     */
     @PostMapping("/assign/{user-id}")
     @PreAuthorize("hasAuthority('ROLE_DRIVER')")
     @Operation(summary = "Assign a vehicle to a user",
@@ -48,6 +58,12 @@ public CustomResponse<String>  assignVehicleToUser(
         return CustomResponse.ok(vehicle.getLicensePlate());
     }
 
+    /**
+     * Retrieves parking details for a vehicle using its license plate number.
+     *
+     * @param licensePlate The license plate number of the vehicle.
+     * @return A CustomResponse containing the parking details of the vehicle.
+     */
     @GetMapping("/get-parking-detail/{licensePlate}")
     @PreAuthorize("hasAuthority('ROLE_DRIVER')")
     @Operation(summary = "Get parking details of a vehicle",

src/main/java/com/project/parkinglot/exception/AlreadyException.java

@@ -4,6 +4,10 @@
 
 import java.io.Serial;
 
+/**
+ * An abstract exception class named {@link AlreadyException} representing the scenario where an entity already exists.
+ * This exception should be extended by specific exception classes for different entities.
+ */
 public abstract class AlreadyException extends RuntimeException {
 
     @Serial