docs(api): add parameter descriptions for app contoller annotations

[zachyale]

Description

Continues the work of improving API controller annotations.

Linked Issue: Loosely associated with #183

Changes

• Added parameter descriptions to the controller annotations modified in docs(api): normalize OpenAPI tagging and operation metadata for app + auth/task endpoints #437

Summary by CodeRabbit

• Documentation
  • Enhanced API documentation with detailed parameter descriptions across all endpoints for improved clarity.
  • Added input validation constraints for date and time parameters to enforce valid ranges (months 1-12, weeks 1-53).

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR enhances API documentation by adding Swagger @Parameter annotations to method parameters across 13 controller classes. Additionally, UserStatsController introduces input validation constraints (@Min/@Max) on numeric query parameters and adds class-level @Validated annotation.

Changes

Cohort / File(s)	Summary
App Controllers booklore-api/src/main/java/org/booklore/app/controller/AppAuthorController, AppBookController, AppFilterController, AppNotebookController, AppSeriesController, AppShelfController	Added Swagger @Parameter annotations with descriptions to request parameters (page, size, sort, dir, libraryId, search, bookId, q, limit, etc.) across six controller endpoints. No changes to routing, defaults, or runtime logic.
Authentication & File Controllers booklore-api/src/main/java/org/booklore/controller/AdditionalFileController, LogoutController, OidcAuthController, OidcGroupMappingController	Added Swagger @Parameter annotations to path variables and request parameters across file upload/download/delete endpoints, OIDC callback/logout methods, and group mapping endpoints. No changes to request handling or authorization logic.
Session & Task Controllers booklore-api/src/main/java/org/booklore/controller/ReadingSessionController, TaskController	Added Swagger @Parameter annotations to bookId, page, size, taskId, and taskType parameters. No changes to control flow or service logic.
User Stats Controller booklore-api/src/main/java/org/booklore/controller/UserStatsController	Added Swagger @Parameter annotations to year/month/week parameters and introduced input validation constraints (@Min/@Max on month and week) across 14 endpoints. Applied class-level @Validated annotation. No changes to statistics calculation logic.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

• grimmory#289: Reintroduces API documentation and endpoints; complements this PR's OpenAPI metadata enrichment.
• grimmory#437: Adds @Tag and @Operation OpenAPI annotations to the same controller classes; works in tandem with this PR's parameter-level documentation.

Suggested labels

backend, enhancement

Suggested reviewers

• imajes
• balazs-szucs

Poem

🐰 With whiskers twitching in delight,
We annotate our docs with all our might,
Each parameter now shines so clear,
Our API's story draws near,
Swagger dancing through the code—hooray! 🎉

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 2.04% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs(api): add parameter descriptions for app contoller annotations' follows conventional commit format with 'docs' type and descriptive scope/subject, despite the typo 'contoller' instead of 'controller'.
Description check	✅ Passed	The PR description includes both required sections (Description and Changes) with meaningful content explaining the purpose and specific changes made, matching the template structure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/add-openapi-parameter-descriptions

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feature/add-openapi-parameter-descriptions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

booklore-api/src/main/java/org/booklore/controller/UserStatsController.java (1)

253-253: Consider adding lower bounds for window-size params (weeks, months).

Line 253 and Line 276 currently allow 0/negative values. Adding @Min(1) keeps these endpoints consistent with the new month/week validation approach.

Suggested diff

-    public ResponseEntity<List<WeeklyListeningTrendResponse>> getWeeklyListeningTrend(
-            `@Parameter`(description = "Number of weeks") `@RequestParam`(defaultValue = "26") int weeks) {
+    public ResponseEntity<List<WeeklyListeningTrendResponse>> getWeeklyListeningTrend(
+            `@Parameter`(description = "Number of weeks") `@RequestParam`(defaultValue = "26") `@Min`(1) int weeks) {
         return ResponseEntity.ok(readingSessionService.getWeeklyListeningTrend(weeks));
     }
@@
-    public ResponseEntity<List<MonthlyPaceResponse>> getMonthlyListeningPace(
-            `@Parameter`(description = "Number of months") `@RequestParam`(defaultValue = "12") int months) {
+    public ResponseEntity<List<MonthlyPaceResponse>> getMonthlyListeningPace(
+            `@Parameter`(description = "Number of months") `@RequestParam`(defaultValue = "12") `@Min`(1) int months) {
         return ResponseEntity.ok(readingSessionService.getMonthlyListeningPace(months));
     }

Also applies to: 276-276

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@booklore-api/src/main/java/org/booklore/controller/UserStatsController.java`
at line 253, The weeks/months request parameters in UserStatsController are
currently unconstrained and can be zero/negative; annotate the parameters (the
`@RequestParam` int weeks and the `@RequestParam` int months in the controller
methods) with javax.validation.constraints.Min(1) to enforce a lower bound
(e.g., `@Min`(1) `@RequestParam`(defaultValue="26") int weeks), add the necessary
import, and ensure the controller (UserStatsController) or the specific handler
methods are covered by Spring validation by adding `@Validated` on the class or
method if not already present so the `@Min` constraint is enforced at runtime.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@booklore-api/src/main/java/org/booklore/controller/UserStatsController.java`:
- Line 253: The weeks/months request parameters in UserStatsController are
currently unconstrained and can be zero/negative; annotate the parameters (the
`@RequestParam` int weeks and the `@RequestParam` int months in the controller
methods) with javax.validation.constraints.Min(1) to enforce a lower bound
(e.g., `@Min`(1) `@RequestParam`(defaultValue="26") int weeks), add the necessary
import, and ensure the controller (UserStatsController) or the specific handler
methods are covered by Spring validation by adding `@Validated` on the class or
method if not already present so the `@Min` constraint is enforced at runtime.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8cf239f1-3f81-42c0-a3e2-c0eb4b544a95

📥 Commits

Reviewing files that changed from the base of the PR and between 35dca81 and 1ac904a.

📒 Files selected for processing (13)

• booklore-api/src/main/java/org/booklore/app/controller/AppAuthorController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppBookController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppFilterController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppNotebookController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppSeriesController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppShelfController.java
• booklore-api/src/main/java/org/booklore/controller/AdditionalFileController.java
• booklore-api/src/main/java/org/booklore/controller/LogoutController.java
• booklore-api/src/main/java/org/booklore/controller/OidcAuthController.java
• booklore-api/src/main/java/org/booklore/controller/OidcGroupMappingController.java
• booklore-api/src/main/java/org/booklore/controller/ReadingSessionController.java
• booklore-api/src/main/java/org/booklore/controller/TaskController.java
• booklore-api/src/main/java/org/booklore/controller/UserStatsController.java

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Test Suite / Backend Tests
• GitHub Check: Test Suite / Frontend Tests
• GitHub Check: Analyze (java-kotlin)

🧰 Additional context used

📓 Path-based instructions (1)

booklore-api/src/**/*.java

📄 CodeRabbit inference engine (AGENTS.md)

booklore-api/src/**/*.java: Use 4-space indentation in Java files and match surrounding Java style
Prefer constructor injection via Lombok patterns already used in the codebase. Do not introduce @Autowired field injection
Use MapStruct for entity/DTO mapping

Files:

• booklore-api/src/main/java/org/booklore/app/controller/AppShelfController.java
• booklore-api/src/main/java/org/booklore/controller/ReadingSessionController.java
• booklore-api/src/main/java/org/booklore/controller/LogoutController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppAuthorController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppNotebookController.java
• booklore-api/src/main/java/org/booklore/controller/OidcAuthController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppSeriesController.java
• booklore-api/src/main/java/org/booklore/controller/OidcGroupMappingController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppFilterController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppBookController.java
• booklore-api/src/main/java/org/booklore/controller/TaskController.java
• booklore-api/src/main/java/org/booklore/controller/UserStatsController.java
• booklore-api/src/main/java/org/booklore/controller/AdditionalFileController.java

🧠 Learnings (5)

📚 Learning: 2026-04-04T15:36:56.558Z

Learnt from: balazs-szucs
Repo: grimmory-tools/grimmory PR: 372
File: booklore-api/src/main/java/org/booklore/app/service/AppBookService.java:357-359
Timestamp: 2026-04-04T15:36:56.558Z
Learning: In `booklore-api/src/main/java/org/booklore/app/service/AppBookService.java`, `shelfId` and `magicShelfId` are mutually exclusive navigation contexts in `getFilterOptions`. A request will never supply both at the same time, so the `else if (shelfId != null)` branch after the `magicBookIds != null` check is intentional and correct — there is no missing shelf-∩-magicShelf intersection case. Do not flag this pattern as a bug.

Applied to files:

• booklore-api/src/main/java/org/booklore/app/controller/AppShelfController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppFilterController.java

📚 Learning: 2026-04-10T08:15:37.436Z

Learnt from: imnotjames
Repo: grimmory-tools/grimmory PR: 449
File: booklore-api/src/main/java/org/booklore/service/book/BookDownloadService.java:139-145
Timestamp: 2026-04-10T08:15:37.436Z
Learning: When using Spring `ContentDisposition.builder(...).filename(name, StandardCharsets.UTF_8).build()` (i.e., explicitly providing UTF-8), the resulting header value should include both the quoted `filename="=?UTF-8?..."` and the RFC 5987 `filename*=` parameters. In this case, any extra ASCII fallback computation (e.g., deriving an ASCII `fallbackFilename` via `NON_ASCII_PATTERN` and calling `.filename(fallbackFilename)`) is likely redundant—prefer calling only `.filename(fallbackName?, StandardCharsets.UTF_8)` as appropriate and let Spring handle the UTF-8 header parameters. Verify by comparing the emitted header for `filename` and `filename*` before deciding to keep an ASCII fallback.

Applied to files:

• booklore-api/src/main/java/org/booklore/app/controller/AppShelfController.java
• booklore-api/src/main/java/org/booklore/controller/ReadingSessionController.java
• booklore-api/src/main/java/org/booklore/controller/LogoutController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppAuthorController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppNotebookController.java
• booklore-api/src/main/java/org/booklore/controller/OidcAuthController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppSeriesController.java
• booklore-api/src/main/java/org/booklore/controller/OidcGroupMappingController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppFilterController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppBookController.java
• booklore-api/src/main/java/org/booklore/controller/TaskController.java
• booklore-api/src/main/java/org/booklore/controller/UserStatsController.java
• booklore-api/src/main/java/org/booklore/controller/AdditionalFileController.java

📚 Learning: 2026-03-26T01:46:48.863Z

Learnt from: CR
Repo: grimmory-tools/grimmory PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-26T01:46:48.863Z
Learning: Applies to booklore-api/src/**/*.java : Prefer constructor injection via Lombok patterns already used in the codebase. Do not introduce `Autowired` field injection

Applied to files:

• booklore-api/src/main/java/org/booklore/app/controller/AppAuthorController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppNotebookController.java
• booklore-api/src/main/java/org/booklore/app/controller/AppBookController.java

📚 Learning: 2026-03-26T02:20:27.862Z

Learnt from: imnotjames
Repo: grimmory-tools/grimmory PR: 198
File: booklore-api/src/main/java/org/booklore/controller/KoboController.java:100-103
Timestamp: 2026-03-26T02:20:27.862Z
Learning: In `booklore-api/src/main/java/org/booklore/controller/KoboController.java`, the Kobo reader device already makes direct outbound connections to Kobo's CDN/servers for other requests (confirmed by imnotjames via testing). Therefore, returning a `307 TEMPORARY_REDIRECT` to `cdn.kobo.com` for non-`BL-` book cover thumbnails (instead of server-side proxying) does NOT introduce a new privacy or behavioral regression — the Kobo device's IP and User-Agent are already exposed to Kobo through other direct requests.

Applied to files:

• booklore-api/src/main/java/org/booklore/controller/OidcAuthController.java

📚 Learning: 2026-03-26T01:46:48.863Z

Learnt from: CR
Repo: grimmory-tools/grimmory PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-26T01:46:48.863Z
Learning: Applies to booklore-api/src/**/*.java : Use MapStruct for entity/DTO mapping

Applied to files:

• booklore-api/src/main/java/org/booklore/app/controller/AppBookController.java

🔀 Multi-repo context grimmory-tools/grimmory-docs

Findings for grimmory-tools/grimmory-docs [::grimmory-tools/grimmory-docs::]

• docs/integration/komga-api.md — multiple Komga API endpoints reference {libraryId} and {bookId} (lines shown by search: ~237–257, 278). These are documentation pages that reference path/query parameter names used in Booklore controllers. [::grimmory-tools/grimmory-docs::]
• docs/integration/opds.md — entries refer to GET /komga/api/v1/books/{id}/file and related book endpoints (lines shown ~141–144). [::grimmory-tools/grimmory-docs::]
• docs/authentication/oidc-settings.md and related auth docs — contain sections on OIDC/back-channel logout and group-mapping (many lines; see search hits). These may be affected in OpenAPI output for OIDC endpoints annotated in the PR. [::grimmory-tools/grimmory-docs::]
• docs/authors.md, docs/series.md, docs/notebook.md, docs/notebook.md, docs/readers/, docs/library/ — general product docs referencing authors/books/series/shelves and pagination/filters (search hits for page/size/libraryId/bookId-like terms across many docs). These are static docs that might need syncing if the project regenerates or publishes updated OpenAPI-driven API docs. [::grimmory-tools/grimmory-docs::]

Assessment

• I found documentation pages that reference the same parameter names and endpoints the PR annotates for OpenAPI. No Java code consumers live here (this repo holds user/docs); the main impact is that API docs generation or published OpenAPI spec used by these docs may change/enrich parameter descriptions. [::grimmory-tools/grimmory-docs::]

🔇 Additional comments (13)

booklore-api/src/main/java/org/booklore/controller/ReadingSessionController.java (1)

7-7: OpenAPI parameter docs were added cleanly without behavior changes.

@Parameter metadata is aligned with existing @PathVariable/@RequestParam bindings and keeps runtime behavior intact.

Also applies to: 48-50

booklore-api/src/main/java/org/booklore/app/controller/AppAuthorController.java (1)

4-4: Parameter descriptions are consistent and useful for API consumers.

Nice improvement to OpenAPI clarity for pagination/filtering and path params, with no change to endpoint behavior.

Also applies to: 29-35, 47-47

booklore-api/src/main/java/org/booklore/app/controller/AppShelfController.java (1)

4-4: Good OpenAPI coverage for magic-shelf paging inputs.

The added @Parameter annotations improve generated docs while preserving current request binding/defaults.

Also applies to: 104-106

booklore-api/src/main/java/org/booklore/app/controller/AppNotebookController.java (1)

4-4: Strong documentation pass across notebook endpoints.

Path/query parameter descriptions are now consistently documented across browse/update/delete routes.

Also applies to: 33-35, 47-52, 64-65, 78-79

booklore-api/src/main/java/org/booklore/controller/LogoutController.java (1)

4-4: Nice improvement documenting the optional Origin header.

This makes the logout contract clearer in OpenAPI without affecting request handling.

Also applies to: 34-34

booklore-api/src/main/java/org/booklore/app/controller/AppSeriesController.java (1)

4-4: Series endpoint parameter docs look good and consistent.

The added descriptions improve discoverability for filtering/sorting/pagination inputs.

Also applies to: 29-35, 52-57

booklore-api/src/main/java/org/booklore/controller/OidcAuthController.java (1)

4-4: OIDC parameter documentation updates are solid.

Good addition of descriptions for callback and logout inputs; this improves API clarity without touching flow logic.

Also applies to: 82-87, 133-137, 155-155

booklore-api/src/main/java/org/booklore/controller/OidcGroupMappingController.java (1)

4-4: Mapping ID parameter documentation is correctly applied.

Both update and delete endpoints now expose clearer path-parameter docs in OpenAPI.

Also applies to: 50-50, 60-60

booklore-api/src/main/java/org/booklore/app/controller/AppBookController.java (1)

41-41: Clean OpenAPI parameter enrichment with no behavioral drift.

These @Parameter(description = ...) additions are consistent and keep request binding/runtime logic intact.

Also applies to: 53-55, 67-67, 79-79, 91-91, 103-103, 115-115, 129-129, 143-145

booklore-api/src/main/java/org/booklore/app/controller/AppFilterController.java (1)

30-32: Looks good — parameter docs are clear and aligned with endpoint inputs.

booklore-api/src/main/java/org/booklore/controller/TaskController.java (1)

70-70: Good annotation-only update on task route parameters.

No functional behavior appears altered; this improves OpenAPI clarity for both endpoints.

Also applies to: 94-94

booklore-api/src/main/java/org/booklore/controller/UserStatsController.java (1)

22-22: Nice validation hardening.

Adding @Validated plus explicit month/week bounds is a solid improvement for request correctness and error consistency.

Also applies to: 50-50, 65-65, 91-91, 105-105, 241-241, 300-300

booklore-api/src/main/java/org/booklore/controller/AdditionalFileController.java (1)

41-41: Looks good — parameter descriptions are consistently applied across file endpoints.

Also applies to: 54-55, 69-73, 86-87, 100-101, 115-116