gin-swagger
gin middleware to automatically generate RESTFUL API documentation with Swagger 2.0.
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- Run the Swag at your Go project root path(for instance
~/root/go-peoject-name), Swag will parse comments and generate required files(docsfolder 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/filesImport following in your code:
import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed filesCanonical example:
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 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 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
Configuration
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 |
| DocExpantion | 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). |