gofiber/swagger

The gofiber/swagger repository is deprecated and no longer maintained. To continue using Swagger with Fiber, migrate to the maintained version located in the Fiber Contrib repository.

New Package: github.com/gofiber/contrib/v3/swaggo

Swagger UI allows you to intercept remote definitions, "Try it out" requests, and OAuth 2.0 requests/responses using JavaScript functions provided via template.JS.

• RequestInterceptor: A function that accepts one argument requestInterceptor(request) and must return the modified request (or a Promise resolving to it).
• ResponseInterceptor: A function that accepts one argument responseInterceptor(response) and must return the modified response (or a Promise resolving to it).
• ShowMutatedRequest: If true, the UI will use the mutated request returned from the RequestInterceptor to generate the displayed curl command.

The Config struct is used to customize the behavior and appearance of the Swagger UI middleware. It allows you to control API definition URLs, UI layout, syntax highlighting, OAuth2 settings, and request/response interception.

When initializing your configuration, it is recommended to use the configDefault helper function to ensure that all fields not explicitly set are populated with their intended default values. This prevents breaking the UI by omitting required internal defaults like Plugins or Presets.

import "github.com/gofiber/swagger"

// Example of creating a custom configuration
cfg := swagger.ConfigDefault
cfg.Title = "My Custom API"
cfg.URL = "/api-docs/swagger.json"
cfg.TryItOutEnabled = true
// Use the helper to ensure all other defaults are applied correctly
finalCfg := swagger.ConfigDefault(cfg)

You can control the syntax highlighting behavior using the SyntaxHighlight field in the Config struct, which takes a *SyntaxHighlightConfig object.

Supported themes for Highlight.js include:

• agate (default)
• arta
• monokai
• nord
• obsidian
• tomorrow-night

SyntaxHighlight: &swagger.SyntaxHighlightConfig{
    Activate: true,
    Theme: "monokai",
}

To enable OAuth2 authentication in Swagger UI, provide an OAuthConfig object to the OAuth field in your Config.

Note: ClientSecret should never be used in production environments as it exposes sensitive information. It is intended for development and testing only.

OAuth: &swagger.OAuthConfig{
    ClientId: "your-client-id",
    AppName:  "Your App Name",
    Scopes:   []string{"read", "write"},
}

The New function accepts optional Config arguments to customize the Swagger middleware. While the full struct definition is not in this file, the middleware utilizes the following logic:

• URL: If cfg.URL is empty, the middleware defaults to doc.json relative to the current prefix.
• InstanceName: Used to retrieve the documentation via swag.ReadDoc(cfg.InstanceName). This must match the instance name used when generating your Swagger documentation.

Note: The middleware automatically handles X-Forwarded-Prefix headers to correctly resolve paths when running behind a proxy.

The Filter field allows you to enable a search box in the Swagger UI top bar to filter tagged operations. It uses a FilterConfig struct.

• Enabled: A boolean to turn filtering on or off.
• Expression: A string used as the initial filter expression. Filtering is case-sensitive and matches the expression anywhere inside the tag.

Filter: swagger.FilterConfig{
    Enabled:    true,
    Expression: "user",
}

The New function returns a fiber.Handler that serves the Swagger UI and the generated documentation JSON. You can use it without arguments to get a default handler, or pass a Config object to customize the behavior.

By default, the middleware serves index.html and doc.json. It also supports serving static assets from the Swagger filesystem.

If no configuration is provided, it uses HandlerDefault which is a pre-initialized instance of the middleware.

import (
	"github.com/gofiber/fiber/v3"
	"github.com/gofiber/gofiber/swagger"
)

func main() {

app := fiber.New()

// Use the default handler
app.Use("/swagger/*", swagger.HandlerDefault)

// Or create a custom handler with configuration
// app.Use("/swagger/*", swagger.New(swagger.Config{ ... }))

app.Listen(":3000")
}

For most standard use cases, you can use the exported HandlerDefault variable. This is a pre-configured instance of the Swagger middleware that requires no additional setup beyond being mounted to a route in your Fiber application.

app.Use("/swagger/*", swagger.HandlerDefault)