swagger

id: swagger title: Swagger

Swagger

Swagger middleware for Fiber. The middleware handles Swagger UI.

Note: Requires Go 1.18 and above

Table of Contents

• Signatures
• Installation
• Examples
• Config
• Default Config

Signatures

func New(config ...swagger.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 middleware:

go get github.com/gofiber/contrib/swagger

Examples

Import the middleware package

import (
  "github.com/gofiber/fiber/v2"
  "github.com/gofiber/contrib/swagger"
)

Using the default config:

app.Use(swagger.New())

Using a custom config:

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

app.Use(swagger.New(cfg))

Use program data for Swagger content:

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

app.Use(swagger.New(cfg))

Using multiple instances of Swagger:

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

// Create Swagger middleware for v2
//
// Swagger will be available at: /api/v2/docs
app.Use(swagger.New(swagger.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
}