feat(backend): add Swagger UI and fix ENV var naming#11
Conversation
- Integrate swaggo/swag: annotate existing handlers, generate docs/swagger/,
mount Swagger UI at /swagger/index.html
- Add make swagger target to regenerate docs after annotation changes
- Add swagger_types.go alias so swaggo resolves domain.HealthStats from handlers
- Suppress [GIN-debug] banner and route table; log a single docs URL on startup
- Use gin.Logger() locally (colorful) and slog middleware in staging/production
- Fix APP_ENV → ENV in .env.example and README to match os.Getenv("ENV") in code
- Document Swagger annotation workflow in CLAUDE.md and backend/docs/swagger.md
github-actions
Bot
added
area: backend
|
Warning Review limit reached
More reviews will be available in 51 minutes and 1 second. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more credits in the billing tab to continue. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. 📝 WalkthroughWalkthroughAdds Swagger/OpenAPI 2.0 support to the backend using swaggo: introduces handler annotations, a domain type alias for swaggo resolution, Gin route registration for Swagger UI, generated spec files ( ChangesSwagger/OpenAPI Integration
ENV Variable Rename
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested labels
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 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
🧹 Nitpick comments (1)
backend/docs/swagger/swagger.json (1)
1-97: ⚖️ Poor tradeoffGenerated Swagger spec looks correct; consider adding security definitions when authentication is implemented.
The OpenAPI 2.0 spec is properly generated and matches the handler contracts. Checkov flags the absence of
securityDefinitionsand security requirements—these are valid observations for production APIs with authentication. Since the current API endpoints (GET / and GET /health) are intentionally unauthenticated, this is not a blocker.When authentication is added to the API in the future, remember to:
- Add
@securityDefinitionsannotations tocmd/api/main.go- Add
@Securityannotations to protected handlers- Regenerate the spec with
make swagger🤖 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 `@backend/docs/swagger/swagger.json` around lines 1 - 97, The generated Swagger specification is currently correct and no immediate changes are required since the API endpoints are intentionally unauthenticated. However, when authentication is implemented in the future, add `@securityDefinitions` annotations to the Swagger comments in cmd/api/main.go to define the security schemes, add `@Security` annotations to the protected endpoint handlers to specify which security schemes they require, and regenerate the spec by running make swagger to incorporate these security definitions into the generated swagger.json file.Source: MCP tools
🤖 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 `@backend/docs/swagger.md`:
- Around line 30-32: The fenced code block containing the swag command is
missing a language specifier, which causes a markdownlint warning. Add the
language identifier "bash" to the opening fence (change ``` to ```bash) to
explicitly declare the code block language and silence the linter.
---
Nitpick comments:
In `@backend/docs/swagger/swagger.json`:
- Around line 1-97: The generated Swagger specification is currently correct and
no immediate changes are required since the API endpoints are intentionally
unauthenticated. However, when authentication is implemented in the future, add
`@securityDefinitions` annotations to the Swagger comments in cmd/api/main.go to
define the security schemes, add `@Security` annotations to the protected endpoint
handlers to specify which security schemes they require, and regenerate the spec
by running make swagger to incorporate these security definitions into the
generated swagger.json file.
🪄 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
Run ID: ca2df1a5-5a58-47e9-9e99-26ad1e5142ba
⛔ Files ignored due to path filters (1)
backend/go.sumis excluded by!**/*.sum
📒 Files selected for processing (15)
CLAUDE.mdREADME.mdbackend/.env.examplebackend/Makefilebackend/cmd/api/main.gobackend/docs/swagger.mdbackend/docs/swagger/docs.gobackend/docs/swagger/swagger.jsonbackend/docs/swagger/swagger.yamlbackend/go.modbackend/internal/server/server.gobackend/internal/transport/handlers/health_handler.gobackend/internal/transport/handlers/hello_handler.gobackend/internal/transport/handlers/routes.gobackend/internal/transport/handlers/swagger_types.go
1 participant
Summary
GET /andGET /health, generatedocs/swagger/, mount Swagger UI at/swagger/index.htmlmake swaggerMakefile target to regenerate docs after annotation changesswagger_types.gotype alias so swaggo can resolvedomain.HealthStatsfrom the handlers package[GIN-debug]banner and route table; log a single docs URL on startup insteadgin.Logger()(colorful) locally and the structured slog middleware in staging/productionAPP_ENV→ENVin.env.exampleand README to matchos.Getenv("ENV")in codeCLAUDE.mdandbackend/docs/swagger.mdTest plan
cd backend && make docker-run && make watch— confirm no[GIN-debug]lines, only bootstrap logs +API docs url=http://localhost:8080/swagger/index.htmlhttp://localhost:8080/swagger/index.html— Swagger UI loads withGET /andGET /healthdocumentedcd backend && make swagger— regeneratesdocs/swagger/cleanly with no errorscd backend && go build ./...— clean buildENV=stagingin.env— confirm structured slog request logs replace Gin's colorful outputSummary by CodeRabbit
Release Notes
New Features
make swaggercommand to regenerate API documentation from source annotations.Documentation
Chores
APP_ENVtoENVwith supported values: local, staging, production.