README ¶
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(docs
folder anddocs/doc.go
) at~/root/go-peoject-name/docs
.
swag init
- Download gin-swagger by using:
go get -u github.com/alvarogf97/gin-swagger
go get -u github.com/swaggo/files
Import following in your code:
import "github.com/alvarogf97/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files
Canonical 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 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/alvarogf97/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) |
Documentation ¶
Index ¶
- func CustomWrapHandler(config *Config, handler *webdav.Handler) gin.HandlerFunc
- func DeepLinking(deepLinking bool) func(c *Config)
- func DefaultModelsExpandDepth(depth int) func(c *Config)
- func DisablingCustomWrapHandler(config *Config, h *webdav.Handler, envName string) gin.HandlerFunc
- func DisablingWrapHandler(h *webdav.Handler, envName string, confs ...func(c *Config)) gin.HandlerFunc
- func DocExpansion(docExpansion string) func(c *Config)
- func URL(url string) func(c *Config)
- func WrapHandler(h *webdav.Handler, confs ...func(c *Config)) gin.HandlerFunc
- type Config
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CustomWrapHandler ¶ added in v1.3.4
func CustomWrapHandler(config *Config, handler *webdav.Handler) gin.HandlerFunc
CustomWrapHandler wraps `http.Handler` into `gin.HandlerFunc`
func DeepLinking ¶ added in v1.3.4
DeepLinking set the swagger deeplinking configuration
func DefaultModelsExpandDepth ¶ added in v1.3.4
DefaultModelsExpandDepth set the default expansion depth for models (set to -1 completely hide the models).
func DisablingCustomWrapHandler ¶ added in v1.3.4
DisablingCustomWrapHandler turn handler off if specified environment variable passed
func DisablingWrapHandler ¶ added in v1.3.4
func DisablingWrapHandler(h *webdav.Handler, envName string, confs ...func(c *Config)) gin.HandlerFunc
DisablingWrapHandler turn handler off if specified environment variable passed
func DocExpansion ¶ added in v1.3.4
DocExpansion list, full, none.
func URL ¶ added in v1.3.4
URL presents the url pointing to API definition (normally swagger.json or swagger.yaml).
func WrapHandler ¶
func WrapHandler(h *webdav.Handler, confs ...func(c *Config)) gin.HandlerFunc
WrapHandler wraps `http.Handler` into `gin.HandlerFunc`.
Types ¶
type Config ¶ added in v1.3.4
type Config struct { //The url pointing to API definition (normally swagger.json or swagger.yaml). Default is `doc.json`. URL string DeepLinking bool DocExpansion string DefaultModelsExpandDepth int }
Config stores ginSwagger configuration variables.
func (Config) ToSwaggerConfig ¶ added in v1.3.6
func (c Config) ToSwaggerConfig() swaggerConfig
Convert the config to a swagger one in order to fill unexposed template values.
Directories ¶
Path | Synopsis |
---|---|
example
|
|
basic/docs
Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT This file was generated by swaggo/swag
|
Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT This file was generated by swaggo/swag |