🔥 feat: Add OpenAPI middleware#3702
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.37% 90.91% -0.46%
==========================================
Files 132 135 +3
Lines 13161 14106 +945
==========================================
+ Hits 12026 12825 +799
- Misses 719 818 +99
- Partials 416 463 +47
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 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.
Already applied in I rechecked the remaining thread items: Screenshot: N/A (no UI changes). |
|
@copilot Integrate the following template into the openapi middleware.
Template: <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>{{ .Title }} - Swagger UI</title>
<link
rel="stylesheet"
href="https://unpkg.com/swagger-ui-dist@5.32.6/swagger-ui.css"
/>
</head>
<body>
<div id="swagger-ui"></div>
<script
src="https://unpkg.com/swagger-ui-dist@5.32.6/swagger-ui-bundle.js"
crossorigin="anonymous"
></script>
<script>
window.addEventListener("load", function () {
const options = {{ .SwaggerOptionsJSON }};
window.ui = SwaggerUIBundle({
url: "{{ .OpenAPIURL }}",
dom_id: "#swagger-ui",
presets: [SwaggerUIBundle.presets.apis],
persistAuthorization: true,
...options,
});
});
</script>
</body>
</html> |
Agent-Logs-Url: https://github.com/gofiber/fiber/sessions/56337982-0f7f-47fa-8adc-3a36b84ff957 Co-authored-by: gaby <835733+gaby@users.noreply.github.com>
Agent-Logs-Url: https://github.com/gofiber/fiber/sessions/56337982-0f7f-47fa-8adc-3a36b84ff957 Co-authored-by: gaby <835733+gaby@users.noreply.github.com>
... Implemented in The OpenAPI middleware now also serves a Swagger UI page using the requested template shape, keeps the spec endpoint separate, and lets you configure the CDN asset URLs through Screenshot: N/A (no UI changes rendered in this environment). |
|
Agent-Logs-Url: https://github.com/gofiber/fiber/sessions/a47ab384-adef-4076-a095-19407c41b332 Co-authored-by: gaby <835733+gaby@users.noreply.github.com>
Applied in
Screenshot: N/A (no UI changes rendered in this environment). |
|
@copilot audit the implementation of this middleware. The end goal is for users to be able to automatically get an openapi.json and swagger page. Similar to how frameworks like FastAPI offer. |
…clusivity per OpenAPI spec Agent-Logs-Url: https://github.com/gofiber/fiber/sessions/15c9fc8c-eb8e-4dd2-a0f5-cb6a56c6c9c3 Co-authored-by: gaby <835733+gaby@users.noreply.github.com>
Audit completed and fixes applied in Fixed:
Audit notes (not bugs, architectural scope for future):
All checks pass: lint (0 issues), modernize, format, markdown, full test suite, CodeQL (0 alerts). Coverage at 90.9%. |
|
@copilot Implement automatic schema/model inference from Go structs, similar to FastAPI's auto-generation capabilities. |
… inference Add SchemaOf() function that generates OpenAPI JSON Schema from Go structs using reflection. Supports all primitive types, nested structs, embedded structs, slices, maps, time.Time, pointers, and custom openapi struct tags for description, example, format, and enum values. Includes 19 schema tests and 1 integration test. All lint checks pass. Agent-Logs-Url: https://github.com/gofiber/fiber/sessions/50af7681-fa58-4657-8390-570ea9fa0316 Co-authored-by: gaby <835733+gaby@users.noreply.github.com>
Implemented in
Usage: type User struct {
ID int `json:"id"`
Name string `json:"name"`
Email string `json:"email" openapi:"format:email"`
}
// In route helpers
app.Post("/users", handler).
RequestBodyWithExample("Create user", true, openapi.SchemaOf(User{}), "", nil, nil, fiber.MIMEApplicationJSON)
// Or in Components for $ref reuse
app.Use(openapi.New(openapi.Config{
Components: map[string]any{
"schemas": map[string]any{"User": openapi.SchemaOf(User{})},
},
}))19 schema unit tests + 1 integration test added. All quality checks pass (lint, format, modernize, betteralign, markdown, full test suite, CodeQL).
Audit completed and fixes applied in Audit findings and fixes:
Schema inference (new in
All checks pass: lint (0 issues), format, modernize, betteralign, markdown (0 errors), full test suite, CodeQL (0 alerts). |
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.