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/swagStarting 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-project-name), Swag will parse comments and generate required files(docsfolder anddocs/doc.go) at~/root/go-project-name/docs.
swag init- Download gin-swagger by using:
go get -u github.com/lzw5399/gin-swagger
go get -u github.com/swaggo/filesImport following in your code:
import "github.com/lzw5399/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed filesNow 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 initcommand to generate a docs, docs generated will be stored atdocs/. - 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 https://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/lzw5399/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
.
├── cmd
│ └── ginsimple
│ └── main.go
├── docs
│ ├── docs.go
│ ├── swagger.json
│ └── swagger.yaml
├── go.mod
├── go.sum
└── internal
├── handlers
│ ├── helloWorld.go
│ └── userHandler.go
└── models
├── profile.go
└── user.go
Inorder generate swagger docs for projects with nested directories run the following command
swag init -g ./cmd/ginsimple/main.go -o cmd/docs-o will set the auto generated file to the specified path
This feature was introduced in swag v1.7.9
You can configure Swagger using different configuration options
func main() {
r := gin.New()
ginSwagger.WrapHandler(swaggerfiles.Handler,
ginSwagger.URL("https://localhost:8080/swagger/doc.json"),
ginSwagger.DefaultModelsExpandDepth(-1))
r.Run()
}| 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 gin 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. |