🔥 feat: Add OpenAPI middleware #3702
Conversation
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. ✨ 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 |
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #3702 +/- ##
==========================================
- Coverage 91.81% 91.63% -0.19%
==========================================
Files 114 117 +3
Lines 11498 10109 -1389
==========================================
- Hits 10557 9263 -1294
+ Misses 681 548 -133
- Partials 260 298 +38
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
/gemini review |
|
Warning Gemini encountered an error creating the review. You can try again by commenting |
|
/gemini review |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new OpenAPI middleware for auto-generating API specifications. The implementation is solid, with good test coverage and documentation. I've identified a potential improvement to prevent the middleware from documenting its own endpoint in the generated spec, which would make the output cleaner for API consumers. I also found a minor formatting issue in the documentation. Overall, this is a great feature addition.
|
nice feature, thx @gaby |
|
/gemini review |
There was a problem hiding this comment.
Pull Request Overview
This PR introduces an OpenAPI middleware that auto-generates OpenAPI 3.0 specifications from registered Fiber routes. The implementation adds per-route metadata capabilities (summary, description, tags, parameters, request/response bodies, deprecation) that can be configured either through fluent route builders or global middleware configuration.
Key changes:
- New OpenAPI middleware package with spec generation and JSON serving
- Extended
Routestruct with OpenAPI-specific metadata fields - Added fluent API methods to both
AppandGroupfor route documentation
Reviewed Changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
middleware/openapi/openapi.go |
Core middleware implementation generating OpenAPI spec from routes |
middleware/openapi/config.go |
Configuration types for middleware and operation metadata |
middleware/openapi/openapi_test.go |
Comprehensive test suite covering spec generation scenarios |
middleware/openapi/testdata/openapi.json |
Golden file fixture for JSON output validation |
router.go |
Extended Route struct with OpenAPI fields and helper types |
router_test.go |
Tests for new route metadata methods |
app.go |
Fluent API methods for documenting routes |
group.go |
Group delegation methods for route documentation |
group_test.go |
Tests for group-level route documentation |
docs/middleware/openapi.md |
User-facing middleware documentation |
docs/whats_new.md |
Release notes entry |
|
@codex review and suggest feature improvements. |
There was a problem hiding this comment.
Code Review
This pull request introduces a new OpenAPI middleware to auto-generate API specifications from routes. The implementation is comprehensive, adding new methods to App and Group for route-level documentation, and providing configuration options for global overrides. The code is well-structured and includes extensive tests.
I have two main points of feedback. The most critical one is that the current implementation incorrectly includes middleware routes (from app.Use) in the generated OpenAPI spec, which should be fixed to ensure a clean and accurate API definition. The other is a minor improvement to an error message for better debugging. Overall, this is a great feature addition.
| if r.Method == fiber.MethodConnect { | ||
| continue | ||
| } |
There was a problem hiding this comment.
Currently, middleware routes (registered with app.Use) are included in the generated OpenAPI specification. This is not ideal as it pollutes the spec with non-endpoint routes (e.g., a logging middleware would appear as an operation for every HTTP method). These routes should be filtered out.
This can be done by checking a flag on the Route struct that indicates if it's a middleware route. Assuming the use field from fiber.Route is exported to Use (as suggested in a separate comment on router.go), you should add a check here to skip middleware routes.
if r.Method == fiber.MethodConnect || r.Use {
continue
}| Produces string `json:"produces"` | ||
| Deprecated bool `json:"deprecated"` | ||
| // Data for routing | ||
| use bool // USE matches path prefixes |
There was a problem hiding this comment.
The use field is internal to the fiber package, which prevents other packages like the openapi middleware from identifying and filtering out middleware routes. This leads to middleware routes being incorrectly included in the generated OpenAPI specification.
To fix this, the use field should be exported (e.g., renamed to Use). This would make it accessible to external packages. Note that this change will require updating all internal usages of this field within the fiber package to use the exported field Use.
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| return func(c fiber.Ctx) error { | ||
| if cfg.Next != nil && cfg.Next(c) { | ||
| return c.Next() | ||
| } | ||
|
|
||
| if !strings.HasSuffix(c.Path(), cfg.Path) { | ||
| return c.Next() | ||
| } |
There was a problem hiding this comment.
The middleware treats any request whose path merely ends with the configured spec path as a hit (strings.HasSuffix(c.Path(), cfg.Path)). This means an instance registered at /openapi.json will intercept unrelated endpoints such as /reports/openapi.json or even other spec handlers for nested groups (/v1/openapi.json), preventing the intended handlers from ever running because the middleware returns the spec immediately. The effect is that legitimate routes become unreachable and multiple OpenAPI endpoints cannot coexist. Consider matching the exact path (or the expected group prefix plus cfg.Path) rather than a simple suffix check before serving the spec.
Useful? React with 👍 / 👎.
Summary
openapi.jsonfile from app routerFixes #2347 #1297 #3118