README.md

id	swaggerui

Swagger UI

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

Swagger UI middleware for Fiber. This handler serves pre-generated Swagger/OpenAPI specs via the swagger-ui package.

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
• Examples
• Config
• Default Config

Signatures

func New(config ...swaggerui.Config) fiber.Handler

Installation

Swagger is tested on the latests Go versions with support for modules. So make sure to initialize one first if you didn't do that yet:

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

And then install the Swagger UI middleware:

go get github.com/gofiber/contrib/v3/swaggerui

Examples

Import the middleware package

import (
  "github.com/gofiber/fiber/v3"
  "github.com/gofiber/contrib/v3/swaggerui"
)

Using the default config:

app.Use(swaggerui.New())

Using a custom config:

cfg := swaggerui.Config{
    BasePath: "/",
    FilePath: "./docs/swagger.json",
    Path:     "swagger",
    Title:    "Swagger API Docs",
}

app.Use(swaggerui.New(cfg))

Use program data for Swagger content:

cfg := swaggerui.Config{
    BasePath:    "/",
    FilePath:    "./docs/swagger.json",
    FileContent: mySwaggerByteSlice,
    Path:        "swagger",
    Title:       "Swagger API Docs",
}

app.Use(swaggerui.New(cfg))

Using multiple instances of Swagger:

// Create Swagger middleware for v1
//
// Swagger will be available at: /api/v1/docs
app.Use(swaggerui.New(swaggerui.Config{
    BasePath: "/api/v1/",
    FilePath: "./docs/v1/swagger.json",
    Path:     "docs",
}))

// Create Swagger middleware for a second API version
//
// Swagger will be available at: /api/v2/docs
app.Use(swaggerui.New(swaggerui.Config{
    BasePath: "/api/v2/",
    FilePath: "./docs/v2/swagger.json",
    Path:     "docs",
}))

Config

type Config struct {
    // Next defines a function to skip this middleware when returned true.
    //
    // Optional. Default: nil
    Next func(c fiber.Ctx) bool

    // BasePath for the UI path
    //
    // Optional. Default: /
    BasePath string

    // FilePath for the swagger.json or swagger.yaml file
    //
    // Optional. Default: ./swagger.json
    FilePath string

    // FileContent for the content of the swagger.json or swagger.yaml file.
    // If provided, FilePath will not be read.
    //
    // Optional. Default: nil
    FileContent []byte

    // Path combines with BasePath for the full UI path
    //
    // Optional. Default: docs
    Path string

    // Title for the documentation site
    //
    // Optional. Default: Fiber API documentation
    Title string

    // CacheAge defines the max-age for the Cache-Control header in seconds.
    //
    // Optional. Default: 3600 (1 hour)
    CacheAge int
}

Default Config

var ConfigDefault = Config{
    Next:     nil,
    BasePath: "/",
    FilePath: "./swagger.json",
    Path:     "docs",
    Title:    "Fiber API documentation",
    CacheAge: 3600, // Default to 1 hour
}