Skip to content
This repository was archived by the owner on Feb 8, 2026. It is now read-only.

feat: prepare swagger v3 for Fiber v3 #114

Closed
ReneWerner87 wants to merge 2 commits into from
Closed

feat: prepare swagger v3 for Fiber v3 #114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4bae034
chore: upgrade to fiber v3
ReneWerner87 Oct 17, 2025
9c9312d
chore: update workflows for go 1.25
ReneWerner87 Oct 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/gotidy.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ jobs:
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: 1.18
go-version: "1.25"
- name: Tidy
run: |
rm -f go.sum
Expand Down
4 changes: 1 addition & 3 deletions .github/workflows/test.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,7 @@ jobs:
strategy:
matrix:
go-version:
- 1.18.x
- 1.20.x
- 1.21.x
- 1.25.x
platform:
- ubuntu-latest
- windows-latest
Expand Down
2 changes: 1 addition & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,5 +11,5 @@
# Output of the go coverage tool, specifically when used with LiteIDE
*.out

# Dependency directories (remove the comment below to include it)
# Vendored dependencies managed via Go modules
vendor/
18 changes: 11 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,19 @@
![Security](https://github.com/gofiber/swagger/workflows/Security/badge.svg)
![Linter](https://github.com/gofiber/swagger/workflows/Linter/badge.svg)

fiber middleware to automatically generate RESTful API documentation with Swagger
fiber middleware to automatically generate RESTful API documentation with Swagger.

> **Note**
>
> Version 3 of this middleware targets Fiber v3 (currently v3.0.0-rc.2) and requires Go 1.25 or newer.

## Usage

1. Add comments to your API source code, [See Declarative Comments Format](https://github.com/swaggo/swag#declarative-comments-format).
2. Download [Swag](https://github.com/swaggo/swag) for Go by using:
```sh
go get -u github.com/swaggo/swag/cmd/swag
# 1.16 or newer
# Go 1.25 or newer
go install github.com/swaggo/swag/cmd/swag@latest
```
3. Run the [Swag](https://github.com/swaggo/swag) in your Go project root folder which contains `main.go` file, [Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`).
Expand All @@ -23,12 +27,12 @@ swag init
```
4. Download [swagger](https://github.com/gofiber/swagger) by using:
```sh
go get -u github.com/gofiber/swagger
go get -u github.com/gofiber/swagger/v3
```
And import following in your code:

```go
import "github.com/gofiber/swagger" // swagger handler
import "github.com/gofiber/swagger/v3" // swagger handler
```

### Canonical example:
Expand All @@ -37,12 +41,12 @@ import "github.com/gofiber/swagger" // swagger handler
package main

import (
"github.com/gofiber/swagger"
"github.com/gofiber/fiber/v2"
"github.com/gofiber/swagger/v3"
"github.com/gofiber/fiber/v3"

// docs are generated by Swag CLI, you have to import them.
// replace with your own docs folder, usually "github.com/username/reponame/docs"
_ "github.com/gofiber/swagger/example/docs"
_ "github.com/gofiber/swagger/v3/example/docs"
)
Comment on lines 43 to 50
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The indentation in this Go code example is inconsistent. Some lines use spaces while others use tabs. It's best practice to format Go code with gofmt, which uses tabs for indentation. This will improve readability and consistency.

Suggested change
import (
"github.com/gofiber/swagger"
"github.com/gofiber/fiber/v2"
"github.com/gofiber/swagger/v3"
"github.com/gofiber/fiber/v3"
// docs are generated by Swag CLI, you have to import them.
// replace with your own docs folder, usually "github.com/username/reponame/docs"
_ "github.com/gofiber/swagger/example/docs"
_ "github.com/gofiber/swagger/v3/example/docs"
)
import (
"github.com/gofiber/swagger/v3"
"github.com/gofiber/fiber/v3"
// docs are generated by Swag CLI, you have to import them.
// replace with your own docs folder, usually "github.com/username/reponame/docs"
_ "github.com/gofiber/swagger/v3/example/docs"
)


// @title Fiber Example API
Expand Down
6 changes: 3 additions & 3 deletions go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
module github.com/gofiber/swagger
module github.com/gofiber/swagger/v3

go 1.18
go 1.25

require (
github.com/gofiber/fiber/v2 v2.52.6
github.com/gofiber/fiber/v3 v3.0.0-rc.2
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

While the fiber dependency has been correctly updated to v3.0.0-rc.2, the go.sum file has not been updated accordingly. It's missing the checksums for the new dependency. Please run go mod tidy to ensure go.sum is complete and correct. An incomplete go.sum will cause build failures for others.

github.com/swaggo/files/v2 v2.0.2
github.com/swaggo/swag v1.16.4
)
Expand Down
2 changes: 0 additions & 2 deletions go.sum
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,6 @@ github.com/go-openapi/spec v0.20.4/go.mod h1:faYFR1CvsJZ0mNsmsphTMSoRrNV3TEDoAM7
github.com/go-openapi/swag v0.19.5/go.mod h1:POnQmlKehdgb5mhVOsnJFsivZCEZ/vjK9gh66Z9tfKk=
github.com/go-openapi/swag v0.19.15 h1:D2NRCBzS9/pEY3gP9Nl8aDqGUcPFrwG2p+CNFrLyrCM=
github.com/go-openapi/swag v0.19.15/go.mod h1:QYRuS/SOXUCsnplDa677K7+DxSOj6IPNl/eQntq43wQ=
github.com/gofiber/fiber/v2 v2.52.6 h1:Rfp+ILPiYSvvVuIPvxrBns+HJp8qGLDnLJawAu27XVI=
github.com/gofiber/fiber/v2 v2.52.6/go.mod h1:YEcBbO/FB+5M1IZNBP9FO3J9281zgPAreiI1oqg8nDw=
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
Expand Down
6 changes: 3 additions & 3 deletions swagger.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@
"strings"
"sync"

"github.com/gofiber/fiber/v2"
"github.com/gofiber/fiber/v2/middleware/filesystem"
"github.com/gofiber/fiber/v2/utils"
"github.com/gofiber/fiber/v3"

Check failure on line 11 in swagger.go

View workflow job for this annotation

GitHub Actions / Tests (1.25.x, ubuntu-latest) 

missing go.sum entry for module providing package github.com/gofiber/fiber/v3 (imported by github.com/gofiber/swagger/v3); to add:

Check failure on line 11 in swagger.go

View workflow job for this annotation

GitHub Actions / golangci

[golangci] swagger.go#L11 

could not import github.com/gofiber/fiber/v3 (swagger.go:11:2: missing go.sum entry for module providing package github.com/gofiber/fiber/v3 (imported by github.com/gofiber/swagger/v3); to add:
Raw output 
swagger.go:11:2: could not import github.com/gofiber/fiber/v3 (swagger.go:11:2: missing go.sum entry for module providing package github.com/gofiber/fiber/v3 (imported by github.com/gofiber/swagger/v3); to add:
	go get github.com/gofiber/swagger/v3) (typecheck)
	"github.com/gofiber/fiber/v3"
	^
"github.com/gofiber/fiber/v3/middleware/filesystem"

Check failure on line 12 in swagger.go

View workflow job for this annotation

GitHub Actions / Tests (1.25.x, ubuntu-latest) 

missing go.sum entry for module providing package github.com/gofiber/fiber/v3/middleware/filesystem (imported by github.com/gofiber/swagger/v3); to add:

Check failure on line 12 in swagger.go

View workflow job for this annotation

GitHub Actions / golangci

[golangci] swagger.go#L12 

could not import github.com/gofiber/fiber/v3/middleware/filesystem (swagger.go:12:2: missing go.sum entry for module providing package github.com/gofiber/fiber/v3/middleware/filesystem (imported by github.com/gofiber/swagger/v3); to add:
Raw output 
swagger.go:12:2: could not import github.com/gofiber/fiber/v3/middleware/filesystem (swagger.go:12:2: missing go.sum entry for module providing package github.com/gofiber/fiber/v3/middleware/filesystem (imported by github.com/gofiber/swagger/v3); to add:
	go get github.com/gofiber/swagger/v3) (typecheck)
	"github.com/gofiber/fiber/v3/middleware/filesystem"
	^
"github.com/gofiber/fiber/v3/utils"

Check failure on line 13 in swagger.go

View workflow job for this annotation

GitHub Actions / Tests (1.25.x, ubuntu-latest) 

missing go.sum entry for module providing package github.com/gofiber/fiber/v3/utils (imported by github.com/gofiber/swagger/v3); to add:

Check failure on line 13 in swagger.go

View workflow job for this annotation

GitHub Actions / golangci

[golangci] swagger.go#L13 

could not import github.com/gofiber/fiber/v3/utils (swagger.go:13:2: missing go.sum entry for module providing package github.com/gofiber/fiber/v3/utils (imported by github.com/gofiber/swagger/v3); to add:
Raw output 
swagger.go:13:2: could not import github.com/gofiber/fiber/v3/utils (swagger.go:13:2: missing go.sum entry for module providing package github.com/gofiber/fiber/v3/utils (imported by github.com/gofiber/swagger/v3); to add:
	go get github.com/gofiber/swagger/v3) (typecheck)
	"github.com/gofiber/fiber/v3/utils"
	^
Comment on lines +11 to +13
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Verify API compatibility with Fiber v3.

The import paths have been updated correctly. However, ensure that the Fiber v3 APIs used in this file (filesystem middleware at line 37, Ctx methods at lines 58-73, and utils at line 58) remain compatible with v3.

Based on learnings, Fiber v3 introduces several API changes including router signature changes and the extractors package for middleware. Please verify that:

  1. The filesystem middleware configuration (line 37) is compatible with v3
  2. Ctx methods like c.Route().Path, c.Path(), c.Params(), c.Type(), c.Redirect() work as expected in v3
  3. The utils.CopyString() function is available in v3

Run the tests after go mod tidy to confirm compatibility:

🏁 Script executed:

#!/bin/bash
# Run tests with v3 dependencies
go mod tidy && go test -v ./...

Length of output: 93

🏁 Script executed:

#!/bin/bash
# Find go.mod file in the repository
echo "=== Locating go.mod file ==="
fd -H "go.mod$" -t f

echo ""
echo "=== Locating swagger.go file ==="
fd -H "swagger.go$" -t f

echo ""
echo "=== Repository structure (first 2 levels) ==="
find . -maxdepth 2 -type f -name "*.go" | head -20

Length of output: 181

🏁 Script executed:

#!/bin/bash
# Examine swagger.go content
echo "=== Full swagger.go content ==="
cat swagger.go

echo ""
echo "=== Go.mod for dependency info ==="
cat go.mod

Length of output: 3384

🌐 Web query:

Fiber v3 Ctx Route Path method API

💡 Result:

Short summary — Fiber v3 Ctx API for route/path/method:

  • c.Route() — returns the matched *Route (contains fields like Method, Path, Params, Handlers). Note: in middleware before c.Next() it returns the last executed route. [1]
  • c.Path(override ...string) string — get (or override by passing a string) the path part of the request. Use c.Path("/new") plus c.RestartRouting() for internal redirects. [1]
  • c.Method(override ...string) string — get the HTTP method (GET/POST/...) or override it by passing a string. [1]
  • Typical usage: inside a handler c.Route().Path, c.Path(), c.Method() to inspect or modify routing/behavior. [1][2]

Docs: Fiber Ctx reference (Ctx.Route / Path / Method) and App routing docs. [1] https://docs.gofiber.io/api/ctx [2] https://docs.gofiber.io/next/api/app

🌐 Web query:

Fiber v3 Ctx Params Type Redirect Redirect method

💡 Result:

Short summary (Fiber v3)

  • Params:
    func (c *Ctx) Params(key string, defaultValue ...string) string. Returns route param (default "" if missing). [1]

  • Redirect (simple):
    func (c *Ctx) Redirect(location string, status ...int) error — redirects to location; status defaults to 302/Found (use 303/307/308 to preserve method). [2]

  • Redirect helper (chainable API):
    func (c *DefaultCtx) Redirect() *Redirect — returns a Redirect object with methods:

    • (*Redirect) To(location string) error
    • (*Redirect) Route(name string, config ...RedirectConfig) error
    • (*Redirect) Back(fallback ...string) error
    • (*Redirect) Status(code int) *Redirect
    • (*Redirect) With(key, value string, level ...uint8) *Redirect
    • (*Redirect) WithInput() *Redirect
      RedirectConfig includes Params (fiber.Map) and Queries (map[string]string). [3]

Sources: Fiber docs and pkg reference. [1] [2] [3]

🌐 Web query:

Fiber v3 Ctx Type method content-type

💡 Result:

Short answer: In GoFiber v3 use c.Type(ext, charset...) to set the response Content-Type by extension (e.g. "json", ".html", "png"). It returns *Ctx so it's chainable. Example:

app.Get("/", func(c *fiber.Ctx) error {
c.Type("json", "utf-8") // sets Content-Type: application/json; charset=utf-8
return c.JSON(fiber.Map{"ok": true})
})

Notes:

  • You may also set any header directly with c.Set("Content-Type", "..."). [1][2]

Sources:
[1] Fiber Ctx API — Type, Set, Is, JSON docs.
[2] pkg.go.dev github.com/gofiber/fiber/v3 (response helpers / defaults).

🌐 Web query:

Fiber v3 filesystem middleware Config Root

💡 Result:

Short answer: In Fiber v3 the old middleware/filesystem was replaced by the new static middleware. Instead of Config.Root (http.FileSystem) on filesystem.Config you now pass the filesystem path or an fs.FS to static.New — or use the contrib/filesystem package which still accepts an http.FileSystem Root. Example usages:

  • static middleware (v3) — pass a root path or os.DirFS:
    app.Get("/*", static.New("./public")) [1]

    or with fs.FS:
    app.Get("/*", static.New("", static.Config{ FS: os.DirFS("./public") })) [1]

  • legacy filesystem middleware (v2 / contrib) — expects Config.Root (http.FileSystem):
    app.Use(filesystem.New(filesystem.Config{ Root: http.FS(embedFS), PathPrefix: "build", Browse: true })) [2]

Reference: Fiber v3 static docs and v3 "What's New" (filesystem -> static), and v2 filesystem Config docs. [1] [3] [2]

🌐 Web query:

Fiber v3 middleware filesystem package deprecated removed

💡 Result:

Short answer: Fiber v3 removed the middleware/filesystem package — you should use the static middleware (static.New with FS: os.DirFS / http.FS / embed.FS or static.Config) instead. See the v3 "What's New" / migration notes and the static middleware docs for examples. [1][2][3]

References:

  • What's New / Migration (notes that filesystem was removed and shows migration examples). [1]
  • Filesystem middleware (v2 reference). [2]
  • Static middleware (v3/next docs showing os.DirFS/http.FS usage). [3]

🌐 Web query:

Fiber v3 contrib filesystem middleware package

💡 Result:

In Fiber v3 the old filesystem middleware was removed from the core — use the new static middleware (which covers filesystem use-cases) or mount an http.FileSystem via static.Config.FS. See Fiber v3 notes and the static middleware docs for examples. [1][2]

Sources:
[1] Fiber v3 "What's New" (Filesystem removed / migrate to static). [2] Fiber static middleware docs (usage + FS example).

🌐 Web query:

Fiber v3 utils CopyString function

💡 Result:

CopyString (in gofiber/utils) makes a heap-allocated copy of a context-derived string by copying its underlying bytes into a new []byte and converting that to string — so the result won't be overwritten by future requests. In practice it does the same as:

buffer := make([]byte, len(s))
copy(buffer, s)
return string(buffer)

In Fiber v3 the utils helpers (including utils.CopyString) are provided from the external module github.com/gofiber/utils/v2. [1][2]

Sources:
[1] Fiber docs — example & CopyString explanation. [2] Fiber v3 “What’s New” / utils migration (notes that CopyString → utils.CopyString and import path).

The filesystem middleware was removed in Fiber v3 and must be updated.

The Ctx methods (c.Route().Path, c.Path(), c.Params(), c.Type(), c.Redirect()) and utils.CopyString() are compatible with Fiber v3. However, the import at line 12 (github.com/gofiber/fiber/v3/middleware/filesystem) no longer exists in v3—the filesystem middleware was removed and replaced with the static middleware.

Line 37's filesystem.New(filesystem.Config{Root: http.FS(swaggerFiles.FS)}) must be refactored to use the static middleware API instead.

🧰 Tools
🪛 GitHub Actions: Tests

[error] 11-11: missing go.sum entry for module providing package github.com/gofiber/fiber/v3 (imported by github.com/gofiber/swagger/v3); to add: go mod tidy

🪛 GitHub Check: golangci

[failure] 11-11: [golangci] swagger.go#L11
could not import github.com/gofiber/fiber/v3 (swagger.go:11:2: missing go.sum entry for module providing package github.com/gofiber/fiber/v3 (imported by github.com/gofiber/swagger/v3); to add:

[failure] 12-12: [golangci] swagger.go#L12
could not import github.com/gofiber/fiber/v3/middleware/filesystem (swagger.go:12:2: missing go.sum entry for module providing package github.com/gofiber/fiber/v3/middleware/filesystem (imported by github.com/gofiber/swagger/v3); to add:

[failure] 13-13: [golangci] swagger.go#L13
could not import github.com/gofiber/fiber/v3/utils (swagger.go:13:2: missing go.sum entry for module providing package github.com/gofiber/fiber/v3/utils (imported by github.com/gofiber/swagger/v3); to add:

🪛 GitHub Check: Tests (1.20.x, ubuntu-latest)

[failure] 13-13:
missing go.sum entry for module providing package github.com/gofiber/fiber/v3/utils (imported by github.com/gofiber/swagger/v3); to add:

[failure] 12-12:
missing go.sum entry for module providing package github.com/gofiber/fiber/v3/middleware/filesystem (imported by github.com/gofiber/swagger/v3); to add:

[failure] 11-11:
missing go.sum entry for module providing package github.com/gofiber/fiber/v3 (imported by github.com/gofiber/swagger/v3); to add:

🪛 GitHub Check: Tests (1.21.x, ubuntu-latest)

[failure] 13-13:
missing go.sum entry for module providing package github.com/gofiber/fiber/v3/utils (imported by github.com/gofiber/swagger/v3); to add:

[failure] 12-12:
missing go.sum entry for module providing package github.com/gofiber/fiber/v3/middleware/filesystem (imported by github.com/gofiber/swagger/v3); to add:

[failure] 11-11:
missing go.sum entry for module providing package github.com/gofiber/fiber/v3 (imported by github.com/gofiber/swagger/v3); to add:

🤖 Prompt for AI Agents 
In swagger.go lines 11-13 and around line 37, replace the removed filesystem
middleware import with Fiber's static middleware import
(github.com/gofiber/fiber/v3/middleware/static) and refactor the middleware
construction: remove filesystem.New(...) and instantiate the static middleware
using the static package's Config that accepts the same root FS
(http.FS(swaggerFiles.FS)); update the route/middleware registration to use
static.New with that Config. Ensure the old filesystem import is deleted and any
filesystem.* references are replaced with static.*.

swaggerFiles "github.com/swaggo/files/v2"
"github.com/swaggo/swag"
)
Expand Down
2 changes: 1 addition & 1 deletion swagger_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import (
"sync"
"testing"

"github.com/gofiber/fiber/v2"
"github.com/gofiber/fiber/v3"
"github.com/swaggo/swag"
)

Expand Down
Loading