什么是swagger
Swagger 是一個用于設計、構建、記錄和使用 RESTful Web 服務的工具集奉瘤。它的主要作用包括：
- API 文檔生成：Swagger 可以自動生成詳細的 API 文檔，包括每個端點的請求和響應格式、參數(shù)狠半、狀態(tài)碼等。這使得開發(fā)者和用戶可以輕松理解和使用 API颤难。
- API 測試：Swagger 提供了一個交互式的界面（Swagger UI）神年，用戶可以直接在瀏覽器中測試 API，而無需編寫額外的客戶端代碼行嗤。
- API 設計：Swagger 支持 API 的設計和規(guī)范定義已日，開發(fā)者可以使用 Swagger 定義 API 的結構和行為，然后生成相應的文檔栅屏。
- 一致性和標準化：通過使用 Swagger飘千，團隊可以確保 API 的設計和實現(xiàn)符合一致的標準和規(guī)范，從而提高代碼質(zhì)量和可維護性栈雳。
- 協(xié)作：Swagger 提供了一個統(tǒng)一的 API 描述格式（OpenAPI Specification）护奈，使得開發(fā)團隊、測試團隊和文檔團隊可以更好地協(xié)作甫恩。
而對于我們的研發(fā)團隊來說逆济，swagger可以清晰的定義接口，即是代碼也是文檔磺箕，大大提升了前后端溝通的效率奖慌，團隊內(nèi)協(xié)作的效率！
而Go - Gin框架支持Swagger松靡，下面一步一步來看下如何使用 swaggo/gin-swagger庫來生成和展示接口文檔简僧。
步驟
步驟 1：安裝依賴
首先，安裝依賴
安裝swag CLI工具
go install github.com/swaggo/swag/cmd/swag@latest
安裝 gin-swagger庫
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
步驟 2：初始化項目
創(chuàng)建一個新的Gin項目或在現(xiàn)有項目中添加Swagger支持雕欺。
go mod init ${your-project-name}
步驟 3：添加注釋
在你的代碼中添加Swagger注釋岛马。例如：
package main
import (
"go-gin-swagger-demo/docs"
"net/http"
"github.com/gin-gonic/gin"
swaggerfiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
)
// @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")
}
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {object} map[string]string
// @Router /example/hi [get]
func Hi(c *gin.Context) {
c.JSON(200, gin.H{
"message": "hi",
})
}
func main() {
r := gin.Default()
docs.SwaggerInfo.BasePath = "/api/v1"
v1 := r.Group("/api/v1")
{
eg := v1.Group("/example")
{
eg.GET("/helloworld", Helloworld)
eg.GET("/hi", Hi)
}
}
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
r.Run(":8080")
}
步驟 4：生成Swagger文檔
由于swag沒被安裝到全局棉姐，先查看swag所在位置
go env GOPATH
運行swag init命令生成Swagger文檔：
${go env GOPATH}/swag init
這將生成docs目錄，其中包含Swagger文檔啦逆。
步驟 5：運行項目
運行你的Gin項目：
go run main.go
然后在瀏覽器中訪問http://localhost:8080/swagger/index.html伞矩，你將看到Swagger UI。
效果展示
通過這些步驟夏志，你可以在Gin項目中集成Swagger乃坤，并生成和展示API文檔。
