introduce swaggo and rename swagger to swaggerui

.github/workflows/test-swaggerui.yml

@@ -0,0 +1,34 @@
+name: "Test swaggerui"
+
+on:
+  push:
+    branches:
+      - master
+      - main
+    paths:
+      - 'v3/swaggerui/**/*.go'
+      - 'v3/swaggerui/go.mod'
+      - 'v3/swaggerui/go.sum'
+  pull_request:
+    paths:
+      - 'v3/swaggerui/**/*.go'
+      - 'v3/swaggerui/go.mod'
+      - 'v3/swaggerui/go.sum'
+
+jobs:
+  Tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go-version:
+          - 1.25.x
+    steps:
+      - name: Fetch Repository
+        uses: actions/checkout@v5
+      - name: Install Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '${{ matrix.go-version }}'
+      - name: Run Test
+        working-directory: ./v3/swaggerui
+        run: go test -v -race ./...

.github/workflows/test-swagger.yml → .github/workflows/test-swaggo.yml

@@ -1,17 +1,19 @@
-name: "Test swagger"
+name: "Test swaggo"
 
 on:
   push:
     branches:
       - master
       - main
     paths:
-      - 'v3/swagger/**/*.go'
-      - 'v3/swagger/go.mod'
+      - 'v3/swaggo/**/*.go'
+      - 'v3/swaggo/go.mod'
+      - 'v3/swaggo/go.sum'
   pull_request:
     paths:
-      - 'v3/swagger/**/*.go'
-      - 'v3/swagger/go.mod'
+      - 'v3/swaggo/**/*.go'
+      - 'v3/swaggo/go.mod'
+      - 'v3/swaggo/go.sum'
 
 jobs:
   Tests:
@@ -28,5 +30,5 @@ jobs:
         with:
           go-version: '${{ matrix.go-version }}'
       - name: Run Test
-        working-directory: ./v3/swagger
+        working-directory: ./v3/swaggo
         run: go test -v -race ./...

README.md

@@ -37,7 +37,8 @@ Repository for third party middlewares and service implementations, with depende
 * [otel (opentelemetry)](./v3/otel/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+otel%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-otel.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="otel workflow status" /> </a>
 * [paseto](./v3/paseto/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+paseto%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-paseto.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="paseto workflow status" /> </a>
 * [socket.io](./v3/socketio/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+socketio%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-socketio.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="socket.io workflow status" /> </a>
-* [swagger](./v3/swagger/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+swagger%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-swagger.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="swagger workflow status" /> </a>
+* [swaggo](./v3/swaggo/README.md) _(formerly `swagger`)_ <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+swaggo%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-swaggo.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="swaggo workflow status" /> </a>
+* [swaggerui](./v3/swaggerui/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+swaggerui%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-swaggerui.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="swaggerui workflow status" /> </a>
 * [websocket](./v3/websocket/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+websocket%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-websocket.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="websocket workflow status" /> </a>
 
 ## 🥡 Service Implementations

go.work

@@ -15,7 +15,8 @@ use (
 ./v3/paseto
 ./v3/sentry
 ./v3/socketio
-./v3/swagger
+    ./v3/swaggo
+./v3/swaggerui
 ./v3/testcontainers
 ./v3/websocket
 ./v3/zap

v3/README.md

@@ -35,7 +35,8 @@ Repository for third party middlewares and service implementations, with depende
 * [otel (opentelemetry)](./otel/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+otel%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-otel.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="otel workflow status" /> </a>
 * [paseto](./paseto/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+paseto%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-paseto.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="paseto workflow status" /> </a>
 * [socket.io](./socketio/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+socketio%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-socketio.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="socket.io workflow status" /> </a>
-* [swagger](./swagger/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+swagger%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-swagger.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="swagger workflow status" /> </a>
+* [swaggo](./swaggo/README.md) _(formerly `swagger`)_ <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+swaggo%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-swaggo.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="swaggo workflow status" /> </a>
+* [swaggerui](./swaggerui/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+swaggerui%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-swaggerui.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="swaggerui workflow status" /> </a>
 * [websocket](./websocket/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+websocket%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-websocket.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" alt="websocket workflow status" /> </a>
 
 ## 🥡 Service Implementations

v3/swagger/README.md → v3/swaggerui/README.md

@@ -1,15 +1,15 @@
 ---
-id: swagger
-title: Swagger
+id: swaggerui
+title: Swagger UI Middleware
 ---
 
-# Swagger
+# Swagger UI Middleware
 
-![Release](https://img.shields.io/github/v/tag/gofiber/contrib?filter=swagger*)
+![Release](https://img.shields.io/github/v/tag/gofiber/contrib?filter=swaggerui*)
 [![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord)
-![Test](https://github.com/gofiber/contrib/workflows/Test%20swagger/badge.svg)
+![Test](https://github.com/gofiber/contrib/workflows/Test%20swaggerui/badge.svg)
 
-Swagger middleware for [Fiber](https://github.com/gofiber/fiber). The middleware handles Swagger UI.
+Swagger UI middleware for [Fiber](https://github.com/gofiber/fiber). This handler serves pre-generated Swagger/OpenAPI specs via the swagger-ui package.
 
 
 **Compatible with Fiber v3.**
@@ -27,64 +27,64 @@ We only support the latest two versions of Go. Visit [https://go.dev/doc/devel/r
 
 ### Signatures
 ```go
-func New(config ...swagger.Config) fiber.Handler
+func New(config ...swaggerui.Config) fiber.Handler
 ```
 
 ### Installation
 Swagger is tested on the latests [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet:
 ```bash
 go mod init github.com/<user>/<repo>
 ```
-And then install the swagger middleware:
+And then install the Swagger UI middleware:
 ```bash
-go get github.com/gofiber/contrib/v3/swagger
+go get github.com/gofiber/contrib/v3/swaggerui
 ```
 
 ### Examples
 Import the middleware package
 ```go
 import (
   "github.com/gofiber/fiber/v3"
-  "github.com/gofiber/contrib/v3/swagger"
+  "github.com/gofiber/contrib/v3/swaggerui"
 )
 ```
 
 Using the default config:
 ```go
-app.Use(swagger.New())
+app.Use(swaggerui.New())
 ```
 
 Using a custom config:
 ```go
-cfg := swagger.Config{
+cfg := swaggerui.Config{
     BasePath: "/",
     FilePath: "./docs/swagger.json",
     Path:     "swagger",
     Title:    "Swagger API Docs",
 }
 
-app.Use(swagger.New(cfg))
+app.Use(swaggerui.New(cfg))
 ```
 
 Use program data for Swagger content:
 ```go
-cfg := swagger.Config{
+cfg := swaggerui.Config{
     BasePath:    "/",
     FilePath:    "./docs/swagger.json",
     FileContent: mySwaggerByteSlice,
     Path:        "swagger",
     Title:       "Swagger API Docs",
 }
 
-app.Use(swagger.New(cfg))
+app.Use(swaggerui.New(cfg))
 ```
 
 Using multiple instances of Swagger:
 ```go
 // Create Swagger middleware for v1
 //
 // Swagger will be available at: /api/v1/docs
-app.Use(swagger.New(swagger.Config{
+app.Use(swaggerui.New(swaggerui.Config{
     BasePath: "/api/v1/",
     FilePath: "./docs/v1/swagger.json",
     Path:     "docs",
@@ -93,7 +93,7 @@ app.Use(swagger.New(swagger.Config{
 // Create Swagger middleware for v2
 //
 // Swagger will be available at: /api/v2/docs
-app.Use(swagger.New(swagger.Config{
+app.Use(swaggerui.New(swaggerui.Config{
     BasePath: "/api/v2/",
     FilePath: "./docs/v2/swagger.json",
     Path:     "docs",

v3/swagger/go.mod → v3/swaggerui/go.mod

@@ -1,4 +1,4 @@
-module github.com/gofiber/contrib/v3/swagger
+module github.com/gofiber/contrib/v3/swaggerui
 
 go 1.25.0
 

v3/swagger/swagger.go → v3/swaggerui/swagger.go

@@ -1,4 +1,4 @@
-package swagger
+package swaggerui
 
 import (
 	"encoding/json"

v3/swagger/swagger_test.go → v3/swaggerui/swagger_test.go

@@ -1,4 +1,4 @@
-package swagger
+package swaggerui
 
 import (
 	_ "embed"

v3/swaggo/README.md

@@ -0,0 +1,144 @@
+---
+id: swaggo
+title: Swaggo – Swagger Doc Generator Middleware (formerly "swagger")
+---
+
+# Swaggo – Swagger Doc Generator Middleware
+
+> ⚠️ This module was renamed from `swagger` to `swaggo` to clearly distinguish it from the ported `swaggerui` middleware. Update your imports accordingly.
+
+![Release](https://img.shields.io/github/v/tag/gofiber/contrib?filter=swaggo*)
+[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord)
+![Test](https://github.com/gofiber/contrib/actions/workflows/test-swaggo.yml/badge.svg)
+
+Swaggo replaces the archived [github.com/gofiber/swagger](https://github.com/gofiber/swagger) module with an actively maintained drop-in generator for [Fiber](https://github.com/gofiber/fiber) v3. It mounts the official Swagger UI, serves the assets required by [swaggo/swag](https://github.com/swaggo/swag) generated documentation, and exposes helper utilities to wire the docs into any Fiber application.
+
+**Compatible with Fiber v3.**
+
+## Go version support
+
+We only support the latest two versions of Go. Visit [https://go.dev/doc/devel/release](https://go.dev/doc/devel/release) for more information.
+
+### Table of Contents
+- [Signatures](#signatures)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Config](#config)
+- [Default Config](#default-config)
+
+### Signatures
+```go
+var HandlerDefault = New()
+func New(config ...Config) fiber.Handler
+```
+
+### Installation
+Swagger Doc Generator is tested on the latest [Go versions](https://go.dev/dl/) with support for modules. Make sure to initialize one first if you have not done that yet:
+```bash
+go mod init github.com/<user>/<repo>
+```
+Then install the middleware:
+```bash
+go get github.com/gofiber/contrib/v3/swaggo
+```
+
+### Usage
+First, document your API using swaggo/swag comments and generate the documentation files (usually inside a `docs` package) by running `swag init`.
+
+```go
+package main
+
+import (
+    "github.com/gofiber/fiber/v3"
+    swaggo "github.com/gofiber/contrib/v3/swaggo"
+
+    // 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/username/reponame/docs"
+)
+
+func main() {
+    app := fiber.New()
+
+    // Mount the UI with the default configuration under /swagger
+    app.Get("/swagger/*", swaggo.HandlerDefault)
+
+    // Customize the UI by passing a Config
+    app.Get("/docs/*", swaggo.New(swaggo.Config{
+        URL:               "http://example.com/doc.json",
+        DeepLinking:       false,
+        DocExpansion:      "none",
+        OAuth2RedirectUrl: "http://localhost:8080/swagger/oauth2-redirect.html",
+    }))
+
+    app.Listen(":8080")
+}
+```
+
+### Config
+```go
+type Config struct {
+    InstanceName              string
+    Title                     string
+    ConfigURL                 string
+    URL                       string
+    QueryConfigEnabled        bool
+    Layout                    string
+    Plugins                   []template.JS
+    Presets                   []template.JS
+    DeepLinking               bool
+    DisplayOperationId        bool
+    DefaultModelsExpandDepth  int
+    DefaultModelExpandDepth   int
+    DefaultModelRendering     string
+    DisplayRequestDuration    bool
+    DocExpansion              string
+    Filter                    FilterConfig
+    MaxDisplayedTags          int
+    ShowExtensions            bool
+    ShowCommonExtensions      bool
+    TagsSorter                template.JS
+    OnComplete                template.JS
+    SyntaxHighlight           *SyntaxHighlightConfig
+    TryItOutEnabled           bool
+    RequestSnippetsEnabled    bool
+    OAuth2RedirectUrl         string
+    RequestInterceptor        template.JS
+    RequestCurlOptions        []string
+    ResponseInterceptor       template.JS
+    ShowMutatedRequest        bool
+    SupportedSubmitMethods    []string
+    ValidatorUrl              string
+    WithCredentials           bool
+    ModelPropertyMacro        template.JS
+    ParameterMacro            template.JS
+    PersistAuthorization      bool
+    OAuth                     *OAuthConfig
+    PreauthorizeBasic         template.JS
+    PreauthorizeApiKey        template.JS
+    CustomStyle               template.CSS
+    CustomScript              template.JS
+}
+```
+
+### Default Config
+```go
+var ConfigDefault = Config{
+    Title:       "Swagger UI",
+    Layout:      "StandaloneLayout",
+    URL:         "doc.json",
+    DeepLinking: true,
+    ShowMutatedRequest: true,
+    Plugins: []template.JS{
+        template.JS("SwaggerUIBundle.plugins.DownloadUrl"),
+    },
+    Presets: []template.JS{
+        template.JS("SwaggerUIBundle.presets.apis"),
+        template.JS("SwaggerUIStandalonePreset"),
+    },
+    SyntaxHighlight: &SyntaxHighlightConfig{Activate: true, Theme: "agate"},
+}
+```
+
+> Refer to [`config.go`](./config.go) for a complete list of options and documentation strings.
+