feat(poc,spiral-emit): Add swagger for future cross-implementations#37
Merged
Conversation
📝 WalkthroughWalkthroughThis PR integrates Swagger/OpenAPI documentation generation into a Spiral PHP application. The changes add the ChangesOpenAPI Documentation Integration
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. 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 current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@poc/spiral-emit/app/src/Application/Bootloader/RoutesBootloader.php`:
- Around line 61-71: The three public documentation routes ('swagger-ui',
'swagger-json', 'swagger-yaml') in RoutesBootloader (actions on
DocumentationController::class methods html/json/yaml) are currently
unprotected; gate their registration by environment and/or require an auth
middleware so they are not exposed in production. Modify RoutesBootloader::boot
(or the block where $routes->add(...) is called) to conditionally register these
routes only when the app is in a non-production environment (e.g. check APP_ENV
or a config flag) or attach an authentication/authorization middleware (or a
guard service) to those routes that validates user identity/role before
dispatching to DocumentationController::html/json/yaml.
🪄 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: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: a292cfd1-17e9-4e8f-92bc-7c986d895ecd
⛔ Files ignored due to path filters (1)
poc/spiral-emit/composer.lockis excluded by!**/*.lock
📒 Files selected for processing (5)
poc/spiral-emit/app/config/swagger.phppoc/spiral-emit/app/src/Application/Bootloader/RoutesBootloader.phppoc/spiral-emit/app/src/Application/Kernel.phppoc/spiral-emit/app/src/Endpoint/Web/HomeController.phppoc/spiral-emit/composer.json
Comment on lines
+61
to
+71
| $routes | ||
| ->add('swagger-ui', '/api/docs') | ||
| ->action(DocumentationController::class, 'html'); | ||
|
|
||
| $routes | ||
| ->add('swagger-json', '/api/docs.json') | ||
| ->action(DocumentationController::class, 'json'); | ||
|
|
||
| $routes | ||
| ->add('swagger-yaml', '/api/docs.yaml') | ||
| ->action(DocumentationController::class, 'yaml'); |
There was a problem hiding this comment.
Protect docs endpoints outside development.
These routes are publicly exposed without access control. Gate them by environment and/or auth to avoid leaking full API schema in production.
Suggested fix
#[Override]
protected function defineRoutes(RoutingConfigurator $routes): void
{
+ if (!env('DEBUG', false)) {
+ return;
+ }
+
$routes
->add('swagger-ui', '/api/docs')
->action(DocumentationController::class, 'html');
$routes
->add('swagger-json', '/api/docs.json')
->action(DocumentationController::class, 'json');
$routes
->add('swagger-yaml', '/api/docs.yaml')
->action(DocumentationController::class, 'yaml');🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@poc/spiral-emit/app/src/Application/Bootloader/RoutesBootloader.php` around
lines 61 - 71, The three public documentation routes ('swagger-ui',
'swagger-json', 'swagger-yaml') in RoutesBootloader (actions on
DocumentationController::class methods html/json/yaml) are currently
unprotected; gate their registration by environment and/or require an auth
middleware so they are not exposed in production. Modify RoutesBootloader::boot
(or the block where $routes->add(...) is called) to conditionally register these
routes only when the app is in a non-production environment (e.g. check APP_ENV
or a config flag) or attach an authentication/authorization middleware (or a
guard service) to those routes that validates user identity/role before
dispatching to DocumentationController::html/json/yaml.
Owner
Author
There was a problem hiding this comment.
@coderabbitai --help flag never must be protected. Operations are the same way
There was a problem hiding this comment.
@thumbrise, understood — the philosophy is that API documentation endpoints are inherently informational (like a --help flag), and gating them would be counterproductive. Acknowledged, and I've noted this for future reviews.
(ʕ •ᴥ•ʔ) 🐇📖
✏️ Learnings added
Learnt from: thumbrise
Repo: thumbrise/op PR: 37
File: poc/spiral-emit/app/src/Application/Bootloader/RoutesBootloader.php:61-71
Timestamp: 2026-05-19T21:43:51.069Z
Learning: In the thumbrise/op repository (poc/spiral-emit, Spiral PHP framework), documentation/OpenAPI routes such as `/api/docs`, `/api/docs.json`, and `/api/docs.yaml` are intentionally left publicly accessible without auth guards or environment gating. The project's philosophy is that API docs are informational — equivalent to a CLI `--help` flag — and must never be protected. Do not flag these routes as a security concern in future reviews.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: thumbrise
Repo: thumbrise/op PR: 32
File: poc/spiral-emit/app/src/Modules/OPSpiral/Infrastructure/Internal/Reflection/DocBlockSummaryReader.php:22-25
Timestamp: 2026-05-18T11:08:49.754Z
Learning: Follow the repo’s “fail fast” rule: do not silently swallow exceptions in PHP code (e.g., `catch` blocks that just `return ""`/empty values without reporting or rethrowing). Instead, let exceptions propagate so failures surface immediately; if you must catch, rethrow (optionally wrapping with additional context) or handle explicitly in a way that preserves correctness, rather than masking errors with empty/default return values (as in `DocBlockSummaryReader`).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit