Skip to content

Commit bde0ec0

Browse files
SporiffSporiff
committed
Clean up code comments
1 parent 0b9f7ec commit bde0ec0

12 files changed

Lines changed: 55 additions & 36 deletions

File tree

‎src/main/java/org/openpodcastapi/opa/auth/AuthDTO.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
/// All data transfer objects for auth methods
77
public class AuthDTO {
8-
/// A DTO representing an API login request
8+
/// A DTO representing an api login request
99
///
1010
/// @param username the user's username
1111
/// @param password the user's password
@@ -15,7 +15,7 @@ public record LoginRequest(
1515
) {
1616
}
1717

18-
/// A DTO representing a successful API authentication attempt
18+
/// A DTO representing a successful api authentication attempt
1919
///
2020
/// @param accessToken the access token to be used to authenticate
2121
/// @param expiresIn the TTL of the access token (in seconds)

src/main/java/org/openpodcastapi/opa/auth/ApiAuthController.java renamed to src/main/java/org/openpodcastapi/opa/controllers/api/AuthController.java

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
1-
package org.openpodcastapi.opa.auth;
1+
package org.openpodcastapi.opa.controllers.api;
22

33
import jakarta.persistence.EntityNotFoundException;
44
import jakarta.validation.constraints.NotNull;
55
import lombok.RequiredArgsConstructor;
66
import lombok.extern.log4j.Log4j2;
7+
import org.openpodcastapi.opa.auth.AuthDTO;
78
import org.openpodcastapi.opa.security.TokenService;
89
import org.openpodcastapi.opa.user.UserEntity;
910
import org.openpodcastapi.opa.user.UserRepository;
@@ -19,11 +20,12 @@
1920
@RestController
2021
@RequiredArgsConstructor
2122
@Log4j2
22-
public class ApiAuthController {
23+
public class AuthController {
2324
private final TokenService tokenService;
2425
private final UserRepository userRepository;
2526
private final AuthenticationManager authenticationManager;
2627

28+
// === Login endpoint ===
2729
@PostMapping("/api/auth/login")
2830
public ResponseEntity<AuthDTO.LoginSuccessResponse> login(@RequestBody @NotNull AuthDTO.LoginRequest loginRequest) {
2931
// Set the authentication using the provided details
@@ -47,6 +49,7 @@ public ResponseEntity<AuthDTO.LoginSuccessResponse> login(@RequestBody @NotNull
4749
return ResponseEntity.ok(response);
4850
}
4951

52+
// === Refresh token endpoint ===
5053
@PostMapping("/api/auth/refresh")
5154
public ResponseEntity<AuthDTO.RefreshTokenResponse> getRefreshToken(@RequestBody @NotNull AuthDTO.RefreshTokenRequest refreshTokenRequest) {
5255
UserEntity targetUserEntity = userRepository.findByUsername(refreshTokenRequest.username()).orElseThrow(() -> new EntityNotFoundException("No user with username " + refreshTokenRequest.username() + " found"));

src/main/java/org/openpodcastapi/opa/controllers/DocsController.java renamed to src/main/java/org/openpodcastapi/opa/controllers/web/DocsController.java

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
package org.openpodcastapi.opa.controllers;
1+
package org.openpodcastapi.opa.controllers.web;
22

33
import lombok.extern.log4j.Log4j2;
44
import org.springframework.stereotype.Controller;
@@ -8,11 +8,13 @@
88
@Log4j2
99
public class DocsController {
1010

11+
// === Docs index page ===
1112
@GetMapping("/docs")
1213
public String docs() {
1314
return "forward:/docs/index.html";
1415
}
1516

17+
// === Docs page with trailing slash ===
1618
@GetMapping("/docs/")
1719
public String docsWithSlash() {
1820
return "forward:/docs/index.html";

src/main/java/org/openpodcastapi/opa/controllers/HomeController.java renamed to src/main/java/org/openpodcastapi/opa/controllers/web/HomeController.java

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
package org.openpodcastapi.opa.controllers;
1+
package org.openpodcastapi.opa.controllers.web;
22

33
import lombok.RequiredArgsConstructor;
44
import lombok.extern.log4j.Log4j2;
@@ -11,11 +11,13 @@
1111
@Log4j2
1212
public class HomeController {
1313

14+
// === Landing page ===
1415
@GetMapping("/")
1516
public String getLandingPage() {
1617
return "landing";
1718
}
1819

20+
// === Authenticated homepage ===
1921
@GetMapping("/home")
2022
public String getHomePage(Authentication auth) {
2123
if (auth != null && !auth.isAuthenticated()) {

src/main/java/org/openpodcastapi/opa/controllers/UiAuthController.java renamed to src/main/java/org/openpodcastapi/opa/controllers/web/WebAuthController.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
package org.openpodcastapi.opa.controllers;
1+
package org.openpodcastapi.opa.controllers.web;
22

33
import jakarta.validation.Valid;
44
import lombok.RequiredArgsConstructor;
@@ -17,7 +17,7 @@
1717
@Controller
1818
@Log4j2
1919
@RequiredArgsConstructor
20-
public class UiAuthController {
20+
public class WebAuthController {
2121
private static final String USER_REQUEST_ATTRIBUTE = "createUserRequest";
2222
private static final String REGISTER_TEMPLATE = "auth/register";
2323
private final UserService userService;

‎src/main/java/org/openpodcastapi/opa/security/TokenService.java‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ public long getExpirationTime() {
4646
return Long.parseLong(jwtExpiration);
4747
}
4848

49-
/// Generates an access token for a given userEntity
49+
/// Generates an access token for a given user
5050
///
5151
/// @param userEntity the [UserEntity] to generate a token for
5252
/// @return the generated token
@@ -61,7 +61,7 @@ public String generateAccessToken(UserEntity userEntity) {
6161
.compact();
6262
}
6363

64-
/// Generates a refresh token for a given userEntity
64+
/// Generates a refresh token for a given user
6565
///
6666
/// @param userEntity the [UserEntity] to generate a refresh token for
6767
/// @return the generated refresh token
@@ -80,13 +80,13 @@ public String generateRefreshToken(UserEntity userEntity) {
8080
return raw;
8181
}
8282

83-
/// Validates the refresh token for a userEntity and updates its expiry time
83+
/// Validates the refresh token for a user and updates its expiry time
8484
///
8585
/// @param rawToken the raw token to validate
8686
/// @param userEntity the [UserEntity] to validate the token for
8787
/// @return the validated [UserEntity]
8888
public UserEntity validateRefreshToken(String rawToken, UserEntity userEntity) {
89-
// Only fetch refresh tokens for the requesting userEntity
89+
// Only fetch refresh tokens for the requesting user
9090
for (RefreshTokenEntity token : repository.findAllByUser(userEntity)) {
9191
// Check that the raw token and the token hash match and the token is not expired
9292
if (passwordEncoder.matches(rawToken, token.getTokenHash()) &&
@@ -95,7 +95,7 @@ public UserEntity validateRefreshToken(String rawToken, UserEntity userEntity) {
9595
token.setExpiresAt(Instant.now().plusSeconds(refreshTokenDays * 24 * 3600));
9696
RefreshTokenEntity updatedToken = repository.save(token);
9797

98-
// Return the userEntity to confirm the token is valid
98+
// Return the user to confirm the token is valid
9999
return updatedToken.getUser();
100100
}
101101
}

‎src/main/java/org/openpodcastapi/opa/subscription/SubscriptionDTO.java‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
import java.util.List;
1111

1212
public class SubscriptionDTO {
13-
/// A DTO representing a new subscriptionEntity
13+
/// A DTO representing a new subscription
1414
///
1515
/// @param feedUrl the URL of the feed
1616
/// @param uuid the UUID of the feed calculated by the client
@@ -20,12 +20,12 @@ public record SubscriptionCreateDTO(
2020
) {
2121
}
2222

23-
/// A DTO representing a user's subscriptionEntity to a given feed
23+
/// A DTO representing a user's subscription to a given feed
2424
///
2525
/// @param uuid the feed UUID
2626
/// @param feedUrl the feed URL
27-
/// @param createdAt the date at which the subscriptionEntity link was created
28-
/// @param updatedAt the date at which the subscriptionEntity link was last updated
27+
/// @param createdAt the date at which the subscription link was created
28+
/// @param updatedAt the date at which the subscription link was last updated
2929
/// @param isSubscribed whether the user is currently subscribed to the feed
3030
public record UserSubscriptionDTO(
3131
@JsonProperty(required = true) @UUID java.util.UUID uuid,
@@ -36,7 +36,7 @@ public record UserSubscriptionDTO(
3636
) {
3737
}
3838

39-
/// A DTO representing a bulk subscriptionEntity creation
39+
/// A DTO representing a bulk subscription creation
4040
///
4141
/// @param success a list of creation successes
4242
/// @param failure a list of creation failures
@@ -46,10 +46,10 @@ public record BulkSubscriptionResponseDTO(
4646
) {
4747
}
4848

49-
/// A DTO representing a failed subscriptionEntity creation
49+
/// A DTO representing a failed subscription creation
5050
///
51-
/// @param uuid the UUID of the failed subscriptionEntity
52-
/// @param feedUrl the feed URL of the failed subscriptionEntity
51+
/// @param uuid the UUID of the failed subscription
52+
/// @param feedUrl the feed URL of the failed subscription
5353
/// @param message the error message explaining the failure
5454
public record SubscriptionFailureDTO(
5555
@JsonProperty(value = "uuid", required = true) @UUID String uuid,

‎src/main/java/org/openpodcastapi/opa/subscription/SubscriptionRestController.java‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,12 @@
2222
public class SubscriptionRestController {
2323
private final SubscriptionService service;
2424

25-
/// Returns all subscriptions for a given userEntity
25+
/// Returns all subscriptions for a given user
2626
///
27-
/// @param user the [CustomUserDetails] of the authenticated userEntity
27+
/// @param user the [CustomUserDetails] of the authenticated user
2828
/// @param pageable the [Pageable] pagination object
2929
/// @param includeUnsubscribed whether to include unsubscribed feeds in the response
30-
/// @return a paginated list of subscriptions
30+
/// @return a [ResponseEntity] containing [SubscriptionDTO.SubscriptionPageDTO] objects
3131
@GetMapping
3232
@ResponseStatus(HttpStatus.OK)
3333
@PreAuthorize("hasRole('USER')")
@@ -46,10 +46,10 @@ public ResponseEntity<SubscriptionDTO.SubscriptionPageDTO> getAllSubscriptionsFo
4646
return new ResponseEntity<>(SubscriptionDTO.SubscriptionPageDTO.fromPage(dto), HttpStatus.OK);
4747
}
4848

49-
/// Returns a single subscriptionEntity entry by UUID
49+
/// Returns a single subscription entry by UUID
5050
///
5151
/// @param uuid the UUID value to query for
52-
/// @return the subscriptionEntity entity
52+
/// @return a [ResponseEntity] containing a [SubscriptionDTO.UserSubscriptionDTO] object
5353
/// @throws EntityNotFoundException if no entry is found
5454
/// @throws IllegalArgumentException if the UUID is improperly formatted
5555
@GetMapping("/{uuid}")
@@ -60,17 +60,17 @@ public ResponseEntity<SubscriptionDTO.UserSubscriptionDTO> getSubscriptionByUuid
6060
// If the value is invalid, the GlobalExceptionHandler will throw a 400.
6161
UUID uuidValue = UUID.fromString(uuid);
6262

63-
// Fetch the subscriptionEntity, throw an EntityNotFoundException if this fails
63+
// Fetch the subscription, throw an EntityNotFoundException if this fails
6464
SubscriptionDTO.UserSubscriptionDTO dto = service.getUserSubscriptionBySubscriptionUuid(uuidValue, user.id());
6565

6666
// Return the mapped subscriptionEntity entry
6767
return new ResponseEntity<>(dto, HttpStatus.OK);
6868
}
6969

70-
/// Updates the subscriptionEntity status of a subscriptionEntity for a given userEntity
70+
/// Updates the subscription status of a subscription for a given user
7171
///
72-
/// @param uuid the UUID of the subscriptionEntity to update
73-
/// @return the updated subscriptionEntity entity
72+
/// @param uuid the UUID of the subscription to update
73+
/// @return a [ResponseEntity] containing a [SubscriptionDTO.UserSubscriptionDTO] object
7474
/// @throws EntityNotFoundException if no entry is found
7575
/// @throws IllegalArgumentException if the UUID is improperly formatted
7676
@PostMapping("/{uuid}/unsubscribe")
@@ -86,10 +86,10 @@ public ResponseEntity<SubscriptionDTO.UserSubscriptionDTO> unsubscribeUserFromFe
8686
return new ResponseEntity<>(dto, HttpStatus.OK);
8787
}
8888

89-
/// Bulk creates UserSubscriptions for a userEntity. Creates new SubscriptionEntity objects if not already present
89+
/// Bulk creates [UserSubscriptionEntity] objects for a user. Creates new [SubscriptionEntity] objects if not already present
9090
///
9191
/// @param request a list of [SubscriptionDTO.SubscriptionCreateDTO] objects
92-
/// @return a [SubscriptionDTO.BulkSubscriptionResponseDTO] object
92+
/// @return a [ResponseEntity] containing a [SubscriptionDTO.BulkSubscriptionResponseDTO] object
9393
@PostMapping
9494
@PreAuthorize("hasRole('USER')")
9595
public ResponseEntity<SubscriptionDTO.BulkSubscriptionResponseDTO> createUserSubscriptions(@RequestBody List<SubscriptionDTO.SubscriptionCreateDTO> request, @AuthenticationPrincipal CustomUserDetails user) {

‎src/main/java/org/openpodcastapi/opa/user/UserDTO.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
import java.util.UUID;
1111

1212
public class UserDTO {
13-
/// A DTO representing a user response over the API
13+
/// A DTO representing a user response over the api
1414
///
1515
/// @param uuid the UUID of the user
1616
/// @param username the username of the user

‎src/main/java/org/openpodcastapi/opa/user/UserRestController.java‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@
1717
public class UserRestController {
1818
private final UserService service;
1919

20+
/// Returns all users
21+
///
22+
/// @param pageable the [Pageable] options used for pagination
23+
/// @return a [ResponseEntity] containing [UserDTO.UserPageDTO] objects
2024
@GetMapping
2125
@ResponseStatus(HttpStatus.OK)
2226
@PreAuthorize("hasRole('ADMIN')")
@@ -26,6 +30,10 @@ public ResponseEntity<UserDTO.UserPageDTO> getAllUsers(Pageable pageable) {
2630
return new ResponseEntity<>(UserDTO.UserPageDTO.fromPage(users), HttpStatus.OK);
2731
}
2832

33+
/// Creates a new user in the system
34+
///
35+
/// @param request a [UserDTO.CreateUserDTO] request body
36+
/// @return a [ResponseEntity] containing [UserDTO.UserResponseDTO] objects
2937
@PostMapping
3038
@ResponseStatus(HttpStatus.CREATED)
3139
public ResponseEntity<UserDTO.UserResponseDTO> createUser(@RequestBody @Validated UserDTO.CreateUserDTO request) {
@@ -36,6 +44,10 @@ public ResponseEntity<UserDTO.UserResponseDTO> createUser(@RequestBody @Validate
3644
return new ResponseEntity<>(dto, HttpStatus.CREATED);
3745
}
3846

47+
/// Fetch a specific user by UUID
48+
///
49+
/// @param uuid the [UUID] of the user
50+
/// @return a [ResponseEntity] containing a summary of the action
3951
@DeleteMapping("/{uuid}")
4052
@PreAuthorize("hasRole('ADMIN') or #uuid == principal.uuid")
4153
public ResponseEntity<String> deleteUser(@PathVariable String uuid) {

0 commit comments

Comments
 (0)