Conversation
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ 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.22% 90.55% -0.67%
==========================================
Files 123 125 +2
Lines 11832 12499 +667
==========================================
+ Hits 10794 11319 +525
- Misses 653 765 +112
- Partials 385 415 +30
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
}
|
@copilot apply changes based on the comments in this thread |
…es, optimize HEAD filtering, fix docs Agent-Logs-Url: https://github.com/gofiber/fiber/sessions/535b1687-97a3-48ff-a2a9-a987bb425aa7 Co-authored-by: gaby <835733+gaby@users.noreply.github.com>
Agent-Logs-Url: https://github.com/gofiber/fiber/sessions/535b1687-97a3-48ff-a2a9-a987bb425aa7 Co-authored-by: gaby <835733+gaby@users.noreply.github.com>
Agent-Logs-Url: https://github.com/gofiber/fiber/sessions/535b1687-97a3-48ff-a2a9-a987bb425aa7 Co-authored-by: gaby <835733+gaby@users.noreply.github.com>
The router_test.go conflict was resolved during the merge in commit
Applied all 9 review comments in commits
Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
|
@copilot apply changes based on the comments in this thread |
…allow explicit requestBody suppression Agent-Logs-Url: https://github.com/gofiber/fiber/sessions/5508bb70-29bd-46df-8dc2-e44f460c9409 Co-authored-by: gaby <835733+gaby@users.noreply.github.com>
Agent-Logs-Url: https://github.com/gofiber/fiber/sessions/5508bb70-29bd-46df-8dc2-e44f460c9409 Co-authored-by: gaby <835733+gaby@users.noreply.github.com>
Applied in commits
|
| // Consumes assigns a request media type to the most recently added route. | ||
| func (app *App) Consumes(typ string) Router { | ||
| if typ != "" { | ||
| if _, _, err := mime.ParseMediaType(typ); err != nil || !strings.Contains(typ, "/") { | ||
| panic("invalid media type: " + typ) | ||
| } | ||
| } | ||
| app.mutex.Lock() | ||
| app.latestRoute.Consumes = typ | ||
| app.mutex.Unlock() | ||
| return app | ||
| } | ||
|
|
||
| // Produces assigns a response media type to the most recently added route. | ||
| func (app *App) Produces(typ string) Router { | ||
| if typ != "" { | ||
| if _, _, err := mime.ParseMediaType(typ); err != nil || !strings.Contains(typ, "/") { | ||
| panic("invalid media type: " + typ) | ||
| } | ||
| } | ||
| app.mutex.Lock() |
There was a problem hiding this comment.
Consumes() / Produces() validate typ without trimming whitespace, while RequestBody/Response media type handling trims and de-dupes. This makes Consumes(" application/json") (or trailing spaces) panic unexpectedly. Consider normalizing via strings.TrimSpace (or reusing the same sanitization helper used elsewhere) before validating/storing.
| | Property | Type | Description | Default | | ||
| |:------------|:------------------------|:----------------------------------------------------------------|:------------------:| | ||
| | Next | `func(fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | | ||
| | Title | `string` | Title is the title for the generated OpenAPI specification. | `"Fiber API"` | | ||
| | Version | `string` | Version is the version for the generated OpenAPI specification. | `"1.0.0"` | | ||
| | Description | `string` | Description is the description for the generated specification. | `""` | | ||
| | ServerURL | `string` | ServerURL is the server URL used in the generated specification.| `""` | | ||
| | Path | `string` | Path is the route where the specification will be served. | `"/openapi.json"` | | ||
| | Operations | `map[string]Operation` | Per-route metadata keyed by `METHOD /path` using Fiber route syntax (e.g. `GET /users/:id`). | `nil` | | ||
|
|
There was a problem hiding this comment.
The config table uses || at the start of each row (e.g. || Property | Type | ...), which is not valid Markdown table syntax and likely won’t render correctly. Use standard table rows starting with a single | for each line.
|
@claude[agent] we want to make sure the implementation is secure and stable. Fix any secure issues you find and potential things that could cause a panic during runtime of he middleware. Note: A panic during initialization/config is fine. |
…checks, improve docs Agent-Logs-Url: https://github.com/gofiber/fiber/sessions/359aa061-8041-46a8-b6c8-46ef09f85838 Co-authored-by: gaby <835733+gaby@users.noreply.github.com>
Security audit completed and hardening applied in commit 9946f64: Security Improvements:
Runtime Panic Analysis:
Tests Added:
All checks pass: lint (0 issues), format, tests (all passing), markdown (0 errors). Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
|
@claude[agent] Improve tests coverage for the openapi middleware. We want to be as close to 90% as possible. |
Agent-Logs-Url: https://github.com/gofiber/fiber/sessions/d38a95ce-ba09-4b0b-b7a7-4cf410b7d7f8 Co-authored-by: gaby <835733+gaby@users.noreply.github.com>
Test coverage improved from 87.5% to 93.1%, exceeding the 90% goal! 🎉 Added comprehensive tests for:
All tests pass with proper parallel execution and zero lint issues. Commit: 8dcfd7c |
Description
This PR introduces an OpenAPI middleware that auto-generates OpenAPI 3.0 specifications from registered Fiber routes. The middleware provides comprehensive support for documenting APIs through both fluent route methods and middleware configuration, making it easy to maintain up-to-date API documentation.
Changes introduced
OpenAPI Middleware Package: New middleware that automatically generates OpenAPI 3.0 JSON specifications from your Fiber application routes
Route Metadata Support: Extended the
Routestruct with OpenAPI-specific fields includingSummary,Description,Tags,Parameters,RequestBody,Responses,Consumes,Produces, andDeprecatedFluent API Methods: Added chainable methods to
App,Group, anddomainRouterfor documenting routes inline (e.g.,.Summary(),.Description(),.Tags(),.Parameter(),.Response(),.RequestBody())Schema References: Support for OpenAPI schema references (
$ref) and examples at the parameter, request body, and response levelsAuto-filtering: Automatically filters out Fiber's auto-generated HEAD routes (via
Route.IsAutoHead()) and middleware routes registered withUse()(viaRoute.IsMiddleware()) to avoid cluttering the spec with synthetic operationsRoute Introspection Methods: Added
IsMiddleware()andIsAutoHead()public methods onRouteto allow middleware and external consumers to distinguish middleware/auto-generated routes from user-defined routesFlexible Configuration: Per-route metadata can be provided via fluent API or global middleware config (keyed by Fiber route syntax, e.g.
GET /users/:id), with config taking precedenceExplicit Request Body Suppression: A non-nil config
RequestBodywith an emptyContentmap is treated as an explicit "no request body" override, preventing the default auto-insertion for POST/PUT/PATCH methodsGroup Support: Correctly handles grouped routes and mounted sub-apps with proper path resolution
Domain Router Support: All OpenAPI fluent methods are implemented on
domainRouter, ensuring domain-scoped routes can be documented identically to standard routesSafe Route Cloning:
copyRoute()deep-clones all OpenAPI-related fields including Tags, Parameters, Responses, and RequestBody to prevent shared backing arrays between mounted/cloned appsImmutable Route Metadata:
App.Tags()defensive-copies the incoming variadic slice before storing, preventing caller-side mutations from affecting route metadataOpenAPI Spec Validity:
buildRequestBody()omits the request body entirely when content is empty, preventing invalid OpenAPI documents with"content":nullMerge Conflict Fixes: Resolved duplicate field declarations in Route struct, handler type conversion issues, semantic conflicts in test files, and integrated parallel benchmark tests from main branch
Code Quality Improvements: Fixed all lint issues (deprecated
utils.ToLowerreplaced withutilsstrings.ToLower, 28 httpNoBody warnings, 5 whyNoLint warnings, 4 paramTypeCombine warnings, 2 hugeParam warnings), applied struct alignment optimizations (reduced Operation struct from 136 to 128 bytes, Media struct from 48 to 40 bytes), and ensured code passes all quality checks with 0 issuesSecurity Hardening:
Consumes()andProduces()now trim whitespace before validation, preventing unexpected panics from inputs like" application/json"or trailing spacesconvertToOpenAPIPath()function that properly converts Fiber route patterns to valid OpenAPI path templates by stripping type constraints (:id<int>→{id}), handling regex constraints, converting wildcards (*and+→{wildcard}), and skipping optional markers (?)appendOrReplaceParameter()to prevent potential runtime panics if code is refactoredconvertToOpenAPIPath()properly guarded with length checks to prevent index out of bounds errorsDocumentation Improvements:
Test Coverage Improvements: Comprehensive test suite with 93.1% code coverage (exceeding 90% goal)
t.Parallel()for concurrent executionmergeConfigParameters(76.9% → 92.3%),buildRequestBody(58.8% → 94.1%),schemaFrom(70.0% → 90.0%),shouldIncludeRequestBody(77.8% → 88.9%),resolvedSpecPath(70.6% → 82.4%),convertMediaContent(63.2% → 78.9%)Benchmarks: No performance impact as spec generation happens once on first request via
sync.Once. Merged 17 parallel benchmark tests from main branch to ensure thread-safety of router operations.Documentation Update: Added comprehensive documentation at
docs/middleware/openapi.mdwith examples and configuration options. Operations key format clarified to use Fiber route syntax (e.g.GET /users/:id). Added explicit caching behavior warnings. All markdown properly formatted and passing linting.Changelog/What's New: OpenAPI middleware enables automatic API documentation generation from route definitions. Default responses documented as
200 OKfor most methods,204 No ContentforDELETEandHEAD. Properly handles Fiber route constraints and wildcards in generated OpenAPI paths.Migration Guide: No migration needed - this is a new opt-in middleware
API Alignment with Express: Not applicable - OpenAPI specification is framework-agnostic
API Longevity: The middleware uses OpenAPI 3.0 standard with extensible configuration structures to accommodate future enhancements. Security hardening ensures production stability.
Examples: Documentation includes examples for basic usage, custom metadata, schema references, grouped routes, and proper middleware registration order
Type of change
Checklist
/docs/directory for Fiber's documentation.📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.