Skip to main content
Version: v3_spnego_v0.x.x

Swaggo

⚠️ This module was renamed from gofiber/swagger to swaggo to clearly distinguish it from the ported swaggerui middleware. Update your imports accordingly.

Release Discord Test

Swaggo replaces the archived github.com/gofiber/swagger module with an actively maintained drop-in generator for Fiber v3. It mounts the official Swagger UI, serves the assets required by 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 for more information.

Table of Contents​

Signatures​

var HandlerDefault = New()
func New(config ...Config) fiber.Handler

Installation​

Swagger Doc Generator is tested on the latest Go versions with support for modules. Make sure to initialize one first if you have not done that yet:

go mod init github.com/<user>/<repo>

Then install the middleware:

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.

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")
}

Behind a reverse proxy​

A proxy that strips a path prefix before forwarding can send it in X-Forwarded-Prefix (for example /api); the redirect and the spec URL in index.html are then prefixed with it. Like Fiber's other X-Forwarded-* handling, the header is honored only from a trusted proxy, so enable TrustProxy and list the proxy in TrustProxyConfig:

app := fiber.New(fiber.Config{
    TrustProxy: true,
    TrustProxyConfig: fiber.TrustProxyConfig{
        Proxies: []string{"10.0.0.1"}, // your proxy
    },
})

Only a plain rooted path is accepted; any other value is ignored. The affected responses carry Vary: X-Forwarded-Prefix, and when the request carries the header, even one that is ignored, private is added to Cache-Control. Make sure the proxy replaces the header rather than appending to one the client sent.

Config​

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​

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 for a complete list of options and documentation strings.