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
- 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
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
- 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
- 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.
- 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",
})
}
- Use
swag init
command to generate a docs, docs generated will be stored at docs/
.
- import the docs like this:
I assume your project named
github.com/go-project-name/docs
.
import (
docs "github.com/go-project-name/docs"
)
-
build your application and after that, go to http://localhost:8888/swagger/index.html ,you to see your Swagger UI.
-
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
Option |
Type |
Default |
Description |
URL |
string |
"doc.json" |
URL pointing to API definition |
DocExpansion |
string |
"list" |
Controls the default expansion setting for the operations and tags. It can be 'list' (expands only the tags), 'full' (expands the tags and operations) or 'none' (expands nothing). |
DeepLinking |
bool |
true |
If set to true, enables deep linking for tags and operations. See the Deep Linking documentation for more information. |
DefaultModelsExpandDepth |
int |
1 |
Default expansion depth for models (set to -1 completely hide the models). |
InstanceName |
string |
"swagger" |
The instance name of the swagger document. If multiple different swagger instances should be deployed on one hertz router, ensure that each instance has a unique name (use the --instanceName parameter to generate swagger documents with swag init). |
PersistAuthorization |
bool |
false |
If set to true, it persists authorization data and it would not be lost on browser close/refresh. |
Oauth2DefaultClientID |
string |
"" |
If set, it's used to prepopulate the client_id field of the OAuth2 Authorization dialog. |