README.md

id	swaggo

Swaggo

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

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
• Installation
• Usage
• Config
• Default Config

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

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.