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
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-project-name
), Swag will parse comments and generate required files(docs
folder 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/files
Import following in your code:
import "github.com/lzw5399/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 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 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/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("http://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. |