gin middleware to automatically generate RESTFUL API documentation with Swagger 2.0.
- 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 at your Go project root path(for instance
~/root/go-peoject-name
), Swag will parse comments and generate required files(docs
folder anddocs/doc.go
) at~/root/go-peoject-name/docs
.
swag init
- Download gin-swagger by using:
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
Import following in your code:
import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files
Now assume you have implemented a simple api as following:
// A get function which returns a hello world string by json
func Helloworld(g *gin.Context) {
g.JSON(http.StatusOK,"helloworld")
}
So how to use gin-swagger on api above? Just follow the following guide.
- Add Comments for apis and main function with gin-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(g *gin.Context) {
g.JSON(http.StatusOK,"helloworld")
}
- Use
swag init
command to generate a docs, docs generated will be stored at - 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:8080/swagger/index.html ,you to see your Swagger UI.
-
The full code and folder relatives here:
package main
import (
"github.com/gin-gonic/gin"
docs "github.com/go-project-name/docs"
swaggerfiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
"net/http"
)
// @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(g *gin.Context) {
g.JSON(http.StatusOK,"helloworld")
}
func main() {
r := gin.Default()
docs.SwaggerInfo.BasePath = "/api/v1"
v1 := r.Group("/api/v1")
{
eg := v1.Group("/example")
{
eg.GET("/helloworld",Helloworld)
}
}
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
r.Run(":8080")
}
Demo project tree, swag init
is run at relative .
.
├── docs
│ ├── docs.go
│ ├── swagger.json
│ └── swagger.yaml
├── go.mod
├── go.sum
└── main.go
You can configure Swagger using different configuration options
func main() {
r := gin.New()
ginSwagger.WrapHandler(swaggerFiles.Handler,
ginSwagger.URL("http://localhost:8080/swagger/doc.json"),
ginSwagger.DefaultModelsExpandDepth(-1)))
r.Run()
}
Option | Type | Default | Description |
---|---|---|---|
URL | string | "doc.json" | URL pointing to API definition |
DeepLinking | bool | true | Swagger deeplinking configuration |
DefaultModelsExpandDepth | int | 1 | Default expansion depth for models (set to -1 completely hide the models) |