https://github.com/yoketh/gofiber-scalar
scalar alternative to swagger for gofiber
https://github.com/yoketh/gofiber-scalar
gofiber golang openapi scalar swagger
Last synced: 4 months ago
JSON representation
scalar alternative to swagger for gofiber
- Host: GitHub
- URL: https://github.com/yoketh/gofiber-scalar
- Owner: yokeTH
- License: bsd-3-clause
- Created: 2025-05-12T15:32:26.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-10-05T21:19:21.000Z (9 months ago)
- Last Synced: 2025-10-05T22:24:17.488Z (9 months ago)
- Topics: gofiber, golang, openapi, scalar, swagger
- Language: Go
- Homepage:
- Size: 7.33 MB
- Stars: 13
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
> [!NOTE]
> Fiber v3 is currently in development and in the release candidate (RC) stage. Since gofiber-scalar follows the same release cycle, it is also in RC. If you’re using Fiber v3, install it with: `go get -u github.com/yokeTH/gofiber-scalar/scalar/v3`
> The stable version of Fiber v3 will be released next week. GoFiber-Scalar The primary branch will be v3, and v2 will no longer be maintained.
# Gofiber Scalar
Scalar middleware for [Fiber](https://github.com/gofiber/fiber). The middleware handles Scalar UI.
**Note: Requires Go 1.23.0 and above**
### Table of Contents
- [Signatures](#signatures)
- [Installation](#installation)
- [Examples](#examples)
- [Config](#config)
- [Default Config](#default-config)
- [Constants](#Constants)
### Signatures
```go
func New(config ...scalar.Config) fiber.Handler
```
### Installation
Scalar is tested on the latest [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet:
```bash
go mod init github.com//
```
And then install the Scalar middleware:
```bash
go get -u github.com/yokeTH/gofiber-scalar/scalar/v2
```
### Examples
Using swaggo to generate documents default output path is `(root)/docs`:
```bash
swag init
# if you use swag-v2
swag init -v3.1
```
Import the middleware package and generated docs
```go
import (
_ "YOUR_MODULE/docs"
"github.com/gofiber/fiber/v2"
"github.com/yokeTH/gofiber-scalar/scalar/v2"
)
```
After Imported:
> For v2, you do not need to register Swag docs manually.
#### Using the default config:
```go
app.Get("/docs/*", scalar.New())
```
Now you can access scalar API documentation UI at `{HOSTNAME}/docs` and JSON documentation at `{HOSTNAME}/docs/doc.json`. Additionally, you can modify the path by configuring the middleware to suit your application's requirements.
Using as the handler: for an example `localhost:8080/yourpath`
```go
app.Get("/yourpath/*", scalar.New(scalar.Config{
Path: "/yourpath",
}))
```
#### Use program data for Swagger content:
```go
cfg := scalar.Config{
BasePath: "/",
FileContentString: jsonString,
Path: "/scalar",
Title: "Scalar API Docs",
}
app.Get("/scalar/*",scalar.New(cfg))
```
#### Use scalar prepared theme
```go
cfg := scalar.Config{
Theme: scalar.ThemeMars,
}
app.Get("/docs/*",scalar.New(cfg))
```
#### Path based reverse proxy
Assuming `/api` is your reverse path, the configuration will use the following order to determine the path:
1. `X-Forwarded-Prefix`
2. `X-Forwarded-Path`
3. `BasePath` (fallback if the headers are not set)
If you cannot configure the headers, you can use `BasePath` as a fallback. Note that this may break in a localhost environment. Example implementation:
```go
cfg = scalar.Config{}
if os.Getenv("APP_ENV") == "PROD" {
cfg.BasePath = "/api"
}
```
### Config
```go
type Config struct {
// BasePath for the UI path
//
// Optional. Default: /
BasePath string
// FileContent for the content of the swagger.json or swagger.yaml file.
//
// Optional. Default: nil
FileContentString string
// 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: 1 min
CacheAge int
// Scalar theme
//
// Optional. Default: ThemeNone
Theme Theme
// Custom Scalar Style
// Ref: https://github.com/scalar/scalar/blob/main/packages/themes/src/variables.css
// Optional. Default: ""
CustomStyle template.CSS
// Proxy to avoid CORS issues
// Optional.
ProxyUrl string
// Raw Space Url
// Optional. Default: doc.json
RawSpecUrl string
// ForceOffline
// Optional: Default: ForceOfflineTrue
ForceOffline *bool
// Fallback scalar cache
//
// Optional. Default: 86400 (1 Days)
FallbackCacheAge int
}
```
### Default Config
```go
var configDefault = Config{
BasePath: "/",
Path: "docs",
Title: "Fiber API documentation",
CacheAge: 60,
Theme: ThemeNone,
RawSpecUrl: "doc.json",
ForceOffline: ForceOfflineTrue,
FallbackCacheAge: 86400,
}
```
### Constants
Theme
```go
const (
ThemeAlternate Theme = "alternate"
ThemeDefault Theme = "default"
ThemeMoon Theme = "moon"
ThemePurple Theme = "purple"
ThemeSolarized Theme = "solarized"
ThemeBluePlanet Theme = "bluePlanet"
ThemeSaturn Theme = "saturn"
ThemeKepler Theme = "kepler"
ThemeMars Theme = "mars"
ThemeDeepSpace Theme = "deepSpace"
ThemeLaserwave Theme = "laserwave"
ThemeNone Theme = "none"
)
var (
ForceOfflineTrue = ptr(true)
ForceOfflineFalse = ptr(false)
)
```