Awesome

Hertz-swagger(This is a community driven project)

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

This repo is forked from gin-swagger and adapted to Hertz.

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

Starting in Go 1.17, installing executables with go get is deprecated. go install may be used instead:

go install github.com/swaggo/swag/cmd/swag@latest

3. 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

4. Download hertz-swagger by using:

go get -u github.com/hertz-contrib/swagger
go get -u github.com/swaggo/files

Import following in your code:

import "github.com/hertz-contrib/swagger" // hertz-swagger middleware
import "github.com/swaggo/files" // swagger embed files

Canonical example:

Now assume you have implemented a simple api as following:

func PingHandler(c context.Context, ctx *app.RequestContext) {
    ctx.JSON(200, map[string]string{
        "ping": "pong",
    })
}

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

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

// PingHandler 测试handler
// @Summary 测试Summary
// @Description 测试Description
// @Accept application/json
// @Produce application/json
// @Router /ping [get]
func PingHandler(c context.Context, ctx *app.RequestContext) {
    ctx.JSON(200, map[string]string{
        "ping": "pong",
    })
}

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

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

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

5. The full code and folder relatives here:

package main

import (
	"context"
	"github.com/cloudwego/hertz/pkg/app"
	"github.com/cloudwego/hertz/pkg/app/server"
	"github.com/hertz-contrib/swagger"
	_ "github.com/hertz-contrib/swagger/example/basic/docs"
	swaggerFiles "github.com/swaggo/files"
)

// PingHandler 测试handler
// @Summary 测试Summary
// @Description 测试Description
// @Accept application/json
// @Produce application/json
// @Router /ping [get]
func PingHandler(c context.Context, ctx *app.RequestContext) {
	ctx.JSON(200, map[string]string{
		"ping": "pong",
	})
}

// @title HertzTest
// @version 1.0
// @description This is a demo using Hertz.

// @contact.name hertz-contrib
// @contact.url https://github.com/hertz-contrib

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8888
// @BasePath /
// @schemes http
func main() {
	h := server.Default()

	h.GET("/ping", PingHandler)

	url := swagger.URL("http://localhost:8888/swagger/doc.json") // The url pointing to API definition
	h.GET("/swagger/*any", swagger.WrapHandler(swaggerFiles.Handler, url))

	h.Spin()
}

Demo project tree, swag init is run at relative .

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

Multiple APIs

This feature was introduced in swag v1.7.9

Configuration

You can configure Swagger using different configuration options