[TOC] > [参考](https://www.topgoer.com/%E5%85%B6%E4%BB%96/Swagger.html） ## 示例 安装 ``` go get -u github.com/swaggo/swag/cmd/swag go get github.com/swaggo/gin-swagger go get github.com/swaggo/gin-swagger/swaggerFiles ``` 在main 中添加 <details> <summary>main.go</summary> ``` package main import ( "net/http" "github.com/gin-gonic/gin" _ "github.com/student/0509/docs" ginSwagger "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles" ) // @title Swagger Example API // @version 1.0 // @description This is a sample server celler server. // @termsOfService https://www.topgoer.com // @contact.name www.topgoer.com // @contact.url https://www.topgoer.com // @contact.email me@razeen.me // @license.name Apache 2.0 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html // @host 127.0.0.1:8080 // @BasePath /api/v1 func main() { r := gin.Default() r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) v1 := r.Group("/api/v1") { v1.GET("/hello", HandleHello) // v1.POST("/login", HandleLogin) // v1Auth := r.Use(HandleAuth) // { // v1Auth.POST("/upload", HandleUpload) // v1Auth.GET("/list", HandleList) // } } r.Run(":8080") } ``` </details> <br/> 执行命令 ``` > swag init 2020/05/13 16:28:02 Generate swagger docs.... 2020/05/13 16:28:02 Generate general API Info, search dir:./ 2020/05/13 16:28:02 create docs.go at docs/docs.go 2020/05/13 16:28:02 create swagger.json at docs/swagger.json 2020/05/13 16:28:02 create swagger.yaml at docs/swagger.yaml ``` 然后我们在`main.go`导入这个自动生成的`docs`包，运行 ``` package main import ( "github.com/gin-gonic/gin" ginSwagger "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles" _ "github.com/razeencheng/demo-go/swaggo-gin/docs" ) // @title Swagger Example API // @version 1.0 // ... ``` 运行 ``` go run main.go ``` 浏览器打开http://127.0.0.1:8080/swagger/index.html  在Handle函数上添加注释 <details> <summary>handle.go</summary> ``` // @Summary 测试SayHello // @Description 向你说Hello // @Tags 测试 // @Accept json // @Param who query string true "人名" // @Success 200 {string} string "{"msg": "hello Razeen"}" // @Failure 400 {string} string "{"msg": "who are you"}" // @Router /hello [get] func HandleHello(c *gin.Context) { who := c.Query("who") if who == "" { c.JSON(http.StatusBadRequest, gin.H{"msg": "who are u?"}) return } c.JSON(http.StatusOK, gin.H{"msg": "hello " + who}) } ``` </details> <br/> ## 优化 在生产环境中,不把文档打包进去 在main.go声明swagHandler,并在该参数不为空时才加入路由： ``` package main //... var swagHandler gin.HandlerFunc func main(){ // ... if swagHandler != nil { r.GET("/swagger/*any", swagHandler) } //... } ``` 我们将该参数在另外加了`build tag`的包中初始化 ``` // +build doc package main import ( _ "github.com/razeencheng/demo-go/swaggo-gin/docs" ginSwagger "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles" ) func init() { swagHandler = ginSwagger.WrapHandler(swaggerFiles.Handler) } ``` `go build -tags "doc"`来打包带文档的包，直接`go build`来打包不带文档的包