fastHttpSwagger

README

fasthttp-swagger

fasthttp middleware to automatically generate RESTFUL API documentation with Swagger 2.0.

Usage

Start using it

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

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

1. Run the Swag at your Go project root path(for instance ~/root/go-peoject-name), Swag will parse comments and generate required files(docs folder and docs/doc.go) at ~/root/go-peoject-name/docs.

swag init

1. Download fasthttp-swagger by using:

go get -u github.com/swaggo/fasthttp-swagger
go get -u github.com/swaggo/files

Import following in your code:

import "github.com/swaggo/fasthttp-swagger" // fasthttp-swagger middleware

Canonical example:

Now assume you have implemented a simple api as following:

// A get function which returns a hello world string by json
func Helloworld(ctx *fasthttp.RequestCtx)  {
    ctx.SetStatusCode(http.StatusOK)
    ctx.Write([]byte("helloworld"))
}

So how to use fasthttp-swagger on api above? Just follow the following guide.

1. Add Comments for apis and main function with fasthttp-swagger rules like following:

// @BasePath /api/v1

// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(ctx *fasthttp.RequestCtx)  {
    ctx.SetStatusCode(http.StatusOK)
    ctx.Write([]byte("helloworld"))
}

1. Use swag init command to generate a docs, docs generated will be stored at
2. import the docs like this: I assume your project named github.com/go-project-name/docs.

import (
   docs "github.com/go-project-name/docs"
)

1. build your application and after that, go to http://localhost:8080/swagger/index.html ,you to see your Swagger UI.

2. The full code and folder relatives here:

package main

import (
   _ "github.com/go-project-name/docs"
   fasthttpSwagger "github.com/swaggo/fasthttp-swagger"
)
// @BasePath /api/v1

// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(ctx *fasthttp.RequestCtx)  {
   ctx.SetStatusCode(http.StatusOK)
   ctx.Write([]byte("helloworld"))
}

func main()  {
   fasthttp.ListenAndServe(":8080", func(ctx *fasthttp.RequestCtx) {
      path := string(ctx.RequestURI())
      switch {
      case strings.HasPrefix(path, "/swagger"):
         fastHttpSwagger.WrapHandler(fastHttpSwagger.InstanceName("swagger"))(ctx)
      case path == "/api/v1/example/helloworld":
         Helloworld(ctx)
      }
   })
}

Demo project tree, swag init is run at relative .

.
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── go.mod
├── go.sum
└── main.go

Documentation

Index

• func CustomWrapHandler(config *Config) fasthttp.RequestHandler
• func DeepLinking(deepLinking bool) func(c *Config)
• func DefaultModelsExpandDepth(depth int) func(c *Config)
• func DisablingCustomWrapHandler(config *Config, envName string) fasthttp.RequestHandler
• func DisablingWrapHandler(envName string) fasthttp.RequestHandler
• func DocExpansion(docExpansion string) func(c *Config)
• func InstanceName(name string) func(c *Config)
• func URL(url string) func(c *Config)
• func WrapHandler(confs ...func(c *Config)) fasthttp.RequestHandler
• type Config
  • func (c Config) ToSwaggerConfig() swaggerConfig

Functions

func CustomWrapHandler

func CustomWrapHandler(config *Config) fasthttp.RequestHandler

CustomWrapHandler wraps `http.Handler` into `gin.HandlerFunc`

func DeepLinking

func DeepLinking(deepLinking bool) func(c *Config)

DeepLinking set the swagger deeplinking configuration

func DefaultModelsExpandDepth

func DefaultModelsExpandDepth(depth int) func(c *Config)

DefaultModelsExpandDepth set the default expansion depth for models (set to -1 completely hide the models).

func DisablingCustomWrapHandler

func DisablingCustomWrapHandler(config *Config, envName string) fasthttp.RequestHandler

DisablingCustomWrapHandler turn handler off if specified environment variable passed

func DisablingWrapHandler

func DisablingWrapHandler(envName string) fasthttp.RequestHandler

DisablingWrapHandler turn handler off if specified environment variable passed

func DocExpansion

func DocExpansion(docExpansion string) func(c *Config)

DocExpansion list, full, none.

func InstanceName

func InstanceName(name string) func(c *Config)

InstanceName set the instance name that was used to generate the swagger documents. Defaults to swag.Name ("swagger").

func URL

func URL(url string) func(c *Config)

URL presents the url pointing to API definition (normally swagger.json or swagger.yaml).

func WrapHandler

func WrapHandler(confs ...func(c *Config)) fasthttp.RequestHandler

WrapHandler wraps `http.Handler` into `gin.HandlerFunc`.

Types

type Config

type Config struct {
	//The url pointing to API definition (normally swagger.json or swagger.yaml). Default is `doc.json`.
	URL                      string
	DeepLinking              bool
	DocExpansion             string
	DefaultModelsExpandDepth int
	InstanceName             string
}

Config stores ginSwagger configuration variables.

func (Config) ToSwaggerConfig

func (c Config) ToSwaggerConfig() swaggerConfig

Convert the config to a swagger one in order to fill unexposed template values.