gofiber/swagger

🧬 fiber middleware to automatically generate RESTful API documentation with Swagger

swagger's Issues

Opinionated: dim background color of swagger a tiny bit to comfort eyes

In UI/UX there is a philosophie, that you never work totally bright nor dark colors. They dimm the color always a bit. I would suggest to do the same with our default swagger. We can make it configureable, but I would recommand to make it default. I'll add two screenshots from my local swagger (ignore the changed logo and accent color) and one with my dark reader browser plugin enabled:

Pleas vote with 👍🏻 or 👎🏻

Failed to load API definition

I'm having an issue where I cannot get the swagger API definition file to load in a K8s environment behind a reverse proxy.

The swagger page (index.html) will load just fine, however it is looking for the json file but cannot find it because it needs to be directed to a slightly modified URL. It is all working locally without issue. I would like it retain the default base URL that it is using, just modify the path slightly. Here is the example:

path to swagger (working): https://<my_api>/v2/swagger/index.html
path it is looking for to load documents: https://<my_api>/swagger/doc.json

The error appears to be that it should be directed to https://<my_api>/v2/swagger/doc.json (which I can get to and view)

Is there a way here to direct it towards the modified path without hard coding the "my_api" portion so that I can keep my builds for staging and production without needing to specify those absolute paths?

in the header, if I modify the "Explore" path from /swagger/doc.json to /v2/swagger/doc.json it works just fine, is there a way I can have it do this automatically?

Ideas for Swagger Middleware

https://github.com/arsmn/fiber-swagger middleware is great but it doesn't have automatic adding feature. Also it will be optional.

I think it can be added like this with hooks:

type UserBody struct{
    Email string `json:"email" swagger:"email,required"`
    Password string `json:"password" swagger:"required"`
}


func main() {
    app := fiber.New()
    swg := swagger.New(app, swagger.Config{})

    swg.Add("index", swagger.Schema{
        Description: "home page",
        Tags: string["home","index"],
        Summary: "qwerty",
        Body: UserBody,
    })

    app.Get("/", func(c *fiber.Ctx) error {
        var user UserBody
        if err := c.BodyParser(&user); err != nil{
            return err
        }

        return c.JSON("👋")
    }).Name("index")
}

cc @balcieren

Declarative comments format is out-of-date

The current link to the declarative comments format documentation seems out-of-date. The new one is here. Could you update the README.md with the new link?

Add Bearer Authentication to Swagger Documentation

I need guidance on how to implement Bearer Authentication in the Swagger documentation for our Fiber middleware. Specifically, I'm unsure about what values to provide for the PreauthorizeApiKey field in the Swagger configuration. Any assistance on how to correctly configure this for Bearer Authentication would be greatly appreciated.

app.Get("/swagger/*", swagger.New(swagger.Config{
	PreauthorizeApiKey: "Bearer",
}))

[BUG] swagger.Config -> 'ShowExtensions' is invalid

I set ShowExtensions to true in the configuration

The source code comments I saw

This is the swagger.json file automatically generated using the [swag] command

x-enum-comments x-enum-varnames are not displayed on swagger ui

[Feature request]: accept option to include custom css

I would be neat to be able to set a custom css on top of the existing one, I personally hate the default color theme used by Shagger, and i think mos developers would prefer a dark them for my api's documentations, so i would like to see if that would be possible.

How?, adding a css string or file descriptor, they would be different fields to differenciate them

Reverse Proxy configuration

Hello.

I use a reverse proxy (Istio+Envoy) and I'm unable to configure swagger using fiber correctly.

I'm configuring the swagger handler like this:

	app.Get("/docs/*", swagger.HandlerDefault)

But when I try to access it from the proxy, which is a URL like this:

https://proxy-host/some/custom/path/docs

The current implementation redirects me to:

https://proxy-host/docs/index.html

Instead of

https://proxy-host/some/custom/path/docs/index.html

The Try it out button also doesn't works because it is trying to send the request to the incorrect path. It should send the request to https://my-proxy-host/custom/path/channels.

Screenshot with this example:

Also, TrustedProxies and EnableTrustedProxyCheck options don't fix this issue. And even it could fix my reverse proxy doesn't have a fixed IP, which would be impossible to configure using the available options. I think you guys should look how Spring Boot manages this and maybe this is even a fiber issue (fixing the c.Redirect func) instead of a gofiber swagger issue: https://docs.spring.io/spring-boot/docs/current/reference/html/howto.html#howto.webserver.use-behind-a-proxy-server

Thanks.

Swagger does not compile on GoFiber v2.50.0

Since the breaking change of GetReqHeaders now returns map[string][]string instead of map[string]string
Code using swagger package no longer compiles.

Fails build here:

https://github.com/gofiber/swagger/blob/main/swagger.go#L81

it is not automatically open api

very hard to impl open api in go lang but in python fastapi is very fast
here all thing occured in coomment it is chip

Swag v2 support

Hi, Swag has a v2 in beta, where they support swagger 3.1. I believe that this library does not work properly with swag v2. Are you planning to support swag v2 either when they release a proper version (not beta) or sooner?

Not compatible with v3

When trying to implement in API code, this error appears:

[{
"message": "cannot use GoSwagger.New(GoSwagger.Config{…}) (value of type func(*"github.com/gofiber/fiber/v2".Ctx) error) as func("github.com/gofiber/fiber/v3".Ctx) error value in argument to app.Get",
}]

Add Unit Tests

I would like to add automated testing to this project.

swagger giving `Cannot GET /index.html`

I'm adding swagger in an application following the README.md in the repository home, as it is.

My problem is when accessing http://localhost:8080/swagger the url is rewritten to http://localhost:8080/index.html and I get the message from the title. I don't get why it is being rewritten.

The swagger endpoint handler is configured as in the README.md:

app := fiber.New()

app.Get("/swagger/*", swagger.HandlerDefault)
// other routes

and dependencies version:

github.com/gofiber/fiber/v2 v2.52.5
github.com/gofiber/swagger v1.1.0

Any ideas?

[BUG] can't load swagger resources when use filesystem middleware for root path

Description

I have embedded front-end building files for my fiber application by filesystem middleware which bundled by statik, but when I try to integrate and set router for swagger like example does, it seems to raise a BUG that loads swagger resources failed.

my environment:

$ go env
GO111MODULE="on"
GOARCH="amd64"
GOBIN=""
GOCACHE="/Users/Bobot/Library/Caches/go-build"
GOENV="/Users/Bobot/Library/Application Support/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOINSECURE=""
GOMODCACHE="/Users/Bobot/go/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="darwin"
GOPATH="/Users/Bobot/go"
GOPRIVATE=""
GOPROXY="https://goproxy.cn,direct"
GOROOT="/usr/local/go"
GOSUMDB="off"
GOTMPDIR=""
GOTOOLDIR="/usr/local/go/pkg/tool/darwin_amd64"
GOVCS=""
GOVERSION="go1.18.3"
GCCGO="gccgo"
GOAMD64="v1"
AR="ar"
CC="clang"
CXX="clang++"
CGO_ENABLED="0"
GOMOD="/Users/Bobot/Repositories/test-restful/go.mod"
GOWORK=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -arch x86_64 -m64 -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/0t/s0c95rbs6ds7w_b0d471p0kc0000gn/T/go-build2147978316=/tmp/go-build -gno-record-gcc-switches -fno-common"

How to reproduce it?

there are minimal steps:

1. my project structure like this:

test-restful
├── dist
│   ├── assets
│   │   └── style.css
│   └── index.html
├── go.mod
├── go.sum
└── main.go

go.mod:

module test-restful

go 1.18

require (
 github.com/gofiber/fiber/v2 v2.41.0
 github.com/gofiber/swagger v0.1.8
 github.com/rakyll/statik v0.1.7
 github.com/swaggo/swag v1.8.10
)

...  // indirect

dist/index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="./assets/style.css" />
    <title>Test</title>
  </head>
  <body>
    <p>Hello, world</p>
  </body>
</html>

dist/assets/style.css:

p {
    font-size: 3.5rem;
    color: red;
    font-weight: bold;
}

2. use statik to build emded file

firstly, install statik:

go get github.com/rakyll/statik
go install github.com/rakyll/statik@latest  # CLI

then run this in test-restful

statik -src=./dist -p bundle -dest=. -f

now the project structure is:

.
├── bundle
│   └── statik.go
├── dist
│   ├── assets
│   │   └── style.css
│   └── index.html
├── go.mod
├── go.sum
└── main.go

3. install swag tool and put comment for main.go

the setup steps same as usage

main.go:

package main

import (
 "github.com/gofiber/fiber/v2"
 "github.com/gofiber/fiber/v2/middleware/filesystem"
 "github.com/gofiber/fiber/v2/middleware/logger"
 "github.com/gofiber/swagger"
 "github.com/rakyll/statik/fs"

 // docs are generated by Swag CLI, you have to import them.
 // replace with your own docs folder, usually "github.com/username/reponame/docs"
 _ "test-restful/bundle"
 _ "test-restful/docs"
)

// @title swagger API
// @version 0.1
// @description swagger api documentations
// @host localhost:8080
// @BasePath /
func main() {
 app := fiber.New()
 app.Use(logger.New())

 statikFS, err := fs.New()
 if err != nil {
  panic("can't embed dist")
 }
 app.Use("/", filesystem.New(filesystem.Config{
  Root: statikFS,
 }))

 app.Get("/swagger/*", swagger.HandlerDefault)
 app.Listen(":8080")
}

and run in terminal:

swag init

finally, just run fiber app and open localhost:8080 in browser:

go run main.go

---

If I use just router but not middleware for root path, the issue seems to be resolved well:

...

 app.Get("/", filesystem.New(filesystem.Config{
  Root: statikFS,
 }))

and then the statik bundle resources (e.g. dist/assets) can't be loaded in reverse.

need to run `swag init` every time to update schema

When i run my app using go run main.go serve (i am using cobra cli framework) then the swagger.json is not update with the updated code (comments). I have to run swag init everytime.

Swag is not recognized as an internal or external command

My trying to run swag init but I got some command error

'swag' is not recognized as an internal or external command, operable program or batch file.

go version 1.18.2
Fiber version 2.33.0

swagger.json is almost empty. No operations defined in spec!

Hi, I'm new to swagger in general. I followed the README. Here is what I did so far.

1. Added few comments to main.go

// @title Fiber Example API
// @version 1.0
// @description This is a sample swagger for Fiber
// @contact.name API Support
// @contact.email [email protected]
// @host localhost:3000
// @BasePath /
func main() {
...
}

2. Added default handler to Fiber instance

app.Get("/swagger/*", swagger.HandlerDefault) // default

3. Imported docs package in the same file as handler.

_ "main/docs"

4. Ran swag init in the root dir of the workspace.

This produces following docs/swagger.json

{
    "swagger": "2.0",
    "info": {
        "description": "This is a sample swagger for Fiber",
        "title": "Fiber Example API",
        "contact": {
            "name": "API Support",
            "email": "[email protected]"
        },
        "version": "1.0"
    },
    "host": "localhost:3000",
    "basePath": "/",
    "paths": {}
}

http://127.0.0.1:3000/swagger/index.html returns No operations defined in spec!

Am I missing anything?

Thanks.

Go fiber swagger

Is there any ways to use gofiber swagger with v3?

I don't want to downgrade from this version because have a lot of codebase but I also don't understand how to work with gofiber/swagger which accepts routes only from v2

Add swaggo instance to config

Deactivating SyntaxHighlight does not seem to work?

I put the following config in my code to turn off syntax highlighting. However, I still get syntax highlights in Swagger UI and for some larger responses it is awfully slow. Any comments on this?

app.Get("/swagger/*", swagger.New(swagger.Config{
  SyntaxHighlight: &swagger.SyntaxHighlightConfig{
    Activate: false,
    Theme:    "",
  },
}))

Expected Behavior
Syntax highlighting should be deactivated.

Current Behavior
Syntax highlighting is still on. For some larger responses it could be really slow.