Product
Introducing License Enforcement in Socket
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
github.com/swaggo/gin-swagger
gin middleware to automatically generate RESTful API documentation with Swagger 2.0.
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
~/root/go-project-name
),
Swag will parse comments and generate required files(docs
folder and docs/doc.go
)
at ~/root/go-project-name/docs
.swag init
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.
// @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")
}
swag init
command to generate a docs, docs generated will be stored at docs/
.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
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. |
FAQs
Unknown package
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Product
We're launching a new set of license analysis and compliance features for analyzing, managing, and complying with licenses across a range of supported languages and ecosystems.
Product
We're excited to introduce Socket Optimize, a powerful CLI command to secure open source dependencies with tested, optimized package overrides.