arsmn / fiber-swagger Goto Github PK

View Code? Open in Web Editor NEW

248.0 3.0 23.0 14.46 MB

fiber middleware to automatically generate RESTful API documentation with Swagger 2.0.

License: MIT License

Go 100.00%

golang fiber middleware swagger fiber-swagger fiber-middleware

fiber-swagger's Introduction

HAS BEEN MOVED TO https://github.com/gofiber/swagger

fiber-swagger

fiber middleware to automatically generate RESTful API documentation with Swagger 2.0.

Usage

Start using it

Add comments to your API source code, See Declarative Comments Format.
Download Swag for Go by using:

$ go get -u github.com/swaggo/swag/cmd/swag

Run the Swag in your Go project root folder which contains main.go file, Swag will parse comments and generate required files(docs folder and docs/doc.go).

$ swag init

Download fiber-swagger by using:

$ go get -u github.com/arsmn/fiber-swagger/v2

And import following in your code:

import "github.com/arsmn/fiber-swagger/v2" // fiber-swagger middleware

Canonical example:

package main

import (
	swagger "github.com/arsmn/fiber-swagger/v2"
	"github.com/gofiber/fiber/v2"

	// docs are generated by Swag CLI, you have to import them.
	// replace with your own docs folder, usually "github.com/username/reponame/docs"
	_ "github.com/arsmn/fiber-swagger/v2/example/docs"
)

// @title Fiber Example API
// @version 1.0
// @description This is a sample swagger for Fiber
// @termsOfService http://swagger.io/terms/
// @contact.name API Support
// @contact.email [email protected]
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host localhost:8080
// @BasePath /
func main() {
	app := fiber.New()

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

	app.Get("/swagger/*", swagger.New(swagger.Config{ // custom
		URL: "http://example.com/doc.json",
		DeepLinking: false,
		// Expand ("list") or Collapse ("none") tag groups by default
		DocExpansion: "none",
		// Prefill OAuth ClientId on Authorize popup
		OAuth: &swagger.OAuthConfig{
			AppName:  "OAuth Provider",
			ClientId: "21bb4edc-05a7-4afc-86f1-2e151e4ba6e2",
		},
		// Ability to change OAuth2 redirect uri location
		OAuth2RedirectUrl: "http://localhost:8080/swagger/oauth2-redirect.html",
	}))

	app.Listen(":8080")
}

Run it, and browser to http://localhost:8080/swagger, you can see Swagger 2.0 Api documents.

fiber-swagger's People

Contributors

Stargazers

Watchers

fiber-swagger's Issues

Manage errors

Hi,
how can I add error handling in swagger ?
regards

cannot find type definition: address.Address

2020/11/17 11:46:44 Generating wallet.Address
2020/11/17 11:46:44 ParseComment error in file api/handlers_transfer.go :cannot find type definition: address.Address

code

package wallet

import(
	"github.com/filecoin-project/go-address"  // package address
)

type AddressBalance struct {
	Addr    address.Address
	Balance types.BigInt
	Default bool
}

License missing

Hi! Could you please add a license to you repository? Otherwise we cannot use it in our company. Thanks in advance!

JWT Authorization Annotations

Which annotations do we need to use for JWT Authorization?

It seems that Swagger is implementing this via bearerAuth: https://swagger.io/docs/specification/authentication/bearer-authentication/

After updating from v2.2.0 to v2.2.4 get javascript error on load

After updating our project to use 2.2.4 eg:
go get: upgraded github.com/arsmn/fiber-swagger/v2 v2.2.0 => v2.24.0

the swagger WebApp started giving a javascript error. I also noticed it did not download the .json file that it normally does, which makes sense with the error as it fails on the downloadSpec() func.

Cannot make Swagger route use the correct doc.json

Hi !

I am trying to use your extension in order set-up correctly a swagger endpoint.

I am very new to Go so it's kind of difficult to debug what's happening as I would like. Feel free to give me any advice.

I have carefully followed the instructions provided in your README file and was not able to get the swagger interface to display my project schema. It keeps displaying the default schema instead.

What I did :

Installed swag
Ran swag init to initialize the ./doc directory with docs.go, swagger.json, swagger.yaml
Added imports to my main.go file
Added declarative comments to my main.go file
Added the default handler to my main.go file
Ran swag init to update the ./doc directory files

main.go:

package main

import (
	"fmt"
	swagger "github.com/arsmn/fiber-swagger"
	_ "github.com/arsmn/fiber-swagger/example/docs"
	"github.com/gofiber/fiber"
	configuration "gitlab.com/xxx/api-media-manager/pkg"
	"gitlab.com/xxx/api-media-manager/pkg/handlers"
)

// @title Media Manager API
// @version 1.0
// @description Media Manager service
func main() {
	/* Get configuration */

	mediaManagerConfiguration := configuration.New()

	/* Set-up server */

	server := fiber.New()

	server.Use("/swagger", swagger.Handler)

	server.Get("/*", handlers.ReadImage)

	/* Run server */

	address := fmt.Sprintf("%s:%d", mediaManagerConfiguration.Host, mediaManagerConfiguration.Port)

	server.Listen(address)
}

Taking a look at ./doc directory files, they are up to date and contain the information defined in my main.go file.

Thanks for your help !

type Type struct {
    FirstName string
}

will be in JSON format:

{ "FirstName": "xxx"}

but the docs render it as

{ "firstName": "xxx"}

Provide swagger.json with application

	var (
		port = envInt("PORT", 4321)
		host = envString("HOST", fmt.Sprintf("http://localhost:%d", port))
	)

	app := fiber.New()
	docs.SwaggerInfo.Host = host
	app.Use("/docs", swagger.New(swagger.Config{ // custom
		URL:         host + "/swagger.json",
		DeepLinking: true,
	}))
	setUpRoutes(app)

unknown revision codec/v1.1.5-pre

go: github.com/arsmn/fiber-swagger/[email protected] requires
	github.com/swaggo/[email protected] requires
	github.com/swaggo/[email protected] requires
	github.com/ugorji/[email protected] requires
	github.com/ugorji/go/[email protected]: reading github.com/ugorji/go/codec/codec/go.mod at revision codec/v1.1.5-pre: unknown revision codec/v1.1.5-pre

To do this, clear the cache and click sync in Goland. It is strange that it is bad at pulling packages automatically :/

$ go get github.com/arsmn/fiber-swagger/v2
go: downloading github.com/arsmn/fiber-swagger/v2 v2.1.3
go: github.com/arsmn/fiber-swagger/v2 upgrade => v2.1.3
go get: github.com/arsmn/fiber-swagger/[email protected] requires
        github.com/swaggo/[email protected] requires
        github.com/swaggo/[email protected] requires
        github.com/ugorji/[email protected] requires
        github.com/ugorji/go/[email protected]: reading github.com/ugorji/go/codec/codec/go.mod at revision codec/v1.1.5-pre: unknown revision codec/v1.1.5-pre

$ go version
go version go1.15.3 linux/amd64