feat(api-docs): reintroduce API doc generation#289
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (9)
✅ Files skipped from review due to trivial changes (6)
🚧 Files skipped from review as they are similar to previous changes (3)
📜 Recent 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)
📝 WalkthroughWalkthroughAdds an opt-in API documentation feature: a conditional controller serving a Scalar UI at /api/docs, an OpenAPI JSON at /api/openapi.json, configuration flags and Springdoc dependency adjustment, and security changes to allow unauthenticated access to the docs endpoints. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant WebApp as Server
participant Springdoc
Client->>WebApp: GET /api/docs
WebApp->>WebApp: SecurityConfig permits public access
WebApp->>WebApp: ScalarController forwards to /scalar.html
Client->>WebApp: GET /scalar.html (static asset)
Client->>WebApp: GET /api/openapi.json
WebApp->>Springdoc: serve OpenAPI JSON (springdoc.api-docs.path)
Springdoc-->>Client: OpenAPI JSON
Client->>Client: Scalar UI renders API reference
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
✨ Simplify code
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@booklore-api/src/main/java/org/booklore/config/security/SecurityConfig.java`:
- Around line 53-54: The security config currently always permits "/api/docs"
and "/api/openapi.json"; change SecurityConfig so those two endpoints are only
added to the permitAll set when the app.api-docs.enabled property is true (e.g.,
inject the boolean property into SecurityConfig as apiDocsEnabled and
conditionally include the paths in the public endpoints list or in the
configure(HttpSecurity http) permitAll call). Update the code that builds the
array/list of public endpoints (or the configure method) to branch on
apiDocsEnabled so the endpoints are not publicly permitted when
app.api-docs.enabled is false.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 451bc3c2-2101-4a9a-8568-91f12dcc7007
📒 Files selected for processing (9)
CONTRIBUTING.mdREADME.mdbooklore-api/CONTRIBUTING.mdbooklore-api/build.gradle.ktsbooklore-api/src/main/java/org/booklore/config/security/SecurityConfig.javabooklore-api/src/main/java/org/booklore/controller/ScalarController.javabooklore-api/src/main/resources/application.yamlbooklore-api/src/main/resources/static/scalar.htmlbooklore-api/src/test/java/org/booklore/controller/ScalarControllerTest.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 / Frontend Tests
- GitHub Check: Test Suite / Backend Tests
- GitHub Check: Analyze (java-kotlin)
🧰 Additional context used
📓 Path-based instructions (2)
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@Autowiredfield injection
Use MapStruct for entity/DTO mapping
Files:
booklore-api/src/test/java/org/booklore/controller/ScalarControllerTest.javabooklore-api/src/main/java/org/booklore/config/security/SecurityConfig.javabooklore-api/src/main/java/org/booklore/controller/ScalarController.java
booklore-api/src/test/**/*.java
📄 CodeRabbit inference engine (AGENTS.md)
Prefer focused unit tests; use
@SpringBootTestonly when the Spring context is required
Files:
booklore-api/src/test/java/org/booklore/controller/ScalarControllerTest.java
🧠 Learnings (2)
📚 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/build.gradle.kts
📚 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/build.gradle.kts
🔇 Additional comments (9)
CONTRIBUTING.md (1)
216-221: Nice documentation addition for API docs discovery.Clear endpoint docs and enablement wording; this aligns well with the feature-flag rollout.
booklore-api/build.gradle.kts (1)
100-100: Dependency swap is aligned with the new docs delivery approach.Using
springdoc-openapi-starter-webmvc-apifits the custom/api/docsUI path and keeps only OpenAPI generation on the backend.booklore-api/src/main/resources/application.yaml (1)
5-6: Config wiring for docs enablement and custom OpenAPI path looks solid.The flag default and springdoc binding are consistent with controlled exposure of API docs.
Also applies to: 98-99
booklore-api/src/main/java/org/booklore/controller/ScalarController.java (1)
7-14: Controller gating and forwarding behavior are cleanly implemented.
@ConditionalOnPropertycorrectly prevents endpoint registration when docs are disabled.README.md (1)
78-80: README updates are clear and operationally useful.The env var, compose passthrough, and endpoint docs are consistent and easy to follow.
Also applies to: 123-123, 201-205
booklore-api/CONTRIBUTING.md (1)
27-35: Good contributor guidance for API docs feature flag behavior.This section accurately communicates default-off behavior and explicit runtime enablement.
booklore-api/src/test/java/org/booklore/controller/ScalarControllerTest.java (1)
16-29: Focused tests with meaningful assertions — nice coverage for the new docs surface.These checks validate both controller forwarding and key Scalar page configuration.
booklore-api/src/main/resources/static/scalar.html (2)
12-16: Good default config for public docs embed.
data-urlandtelemetry:falseare set cleanly and align with exposing/api/openapi.jsonwhile minimizing analytics leakage.
17-17:and
booklore-api/src/main/java/org/booklore/config/security/SecurityConfig.java
Show resolved
Hide resolved
|
@zachyale can you address the coderabbit note? That seems valid |
- reintroduces API doc generation via API_DOCS_ENABLED - accessible publicly via /api/docs and /api/openapi.json
zachyale
force-pushed
the
feat/reintroduce-openapi-and-api-docs
branch
from
fada371 to
b184c8f
Compare
Some context:
RE: the coderabbit note:
|
|
I think we would want to enable this in the dev-docker by default. As well as giving some UI hints towards access. 
I always liked that. The latter is just an idea, but the former would be great if we could implement it here. |
3 participants
Description
This PR reintroduces API reference documentation. It does so by introducing a new env variable,
API_DOCS_ENABLED(defaultfalse).When enabled, docs are available publicly at
.../api/docs, and the JSON spec at.../api/openapi.json.Linked Issue: #288
Changes
app.api-docs.enabledthe value of a new env var,API_DOCS_ENABLED, or defaults to falsespringdoc.api-docs.enabledto use the value ofapp.api-docs.enabled/api/openapi.jsonScalarControllerto server Scalar API docs via/api/docs(if enabled) using the generated OpenAPI json/api/openapi.jsonand"/api/docsto the common public routes list inSecurityConfigSummary by CodeRabbit
New Features
Documentation
Tests