什么是swagger
Swagger 是一个用于设计、构建、记录和使用 RESTful Web 服务的工具集。它的主要作用包括：
- API 文档生成：Swagger 可以自动生成详细的 API 文档，包括每个端点的请求和响应格式、参数、状态码等。这使得开发者和用户可以轻松理解和使用 API。
- API 测试：Swagger 提供了一个交互式的界面（Swagger UI），用户可以直接在浏览器中测试 API，而无需编写额外的客户端代码。
- API 设计：Swagger 支持 API 的设计和规范定义，开发者可以使用 Swagger 定义 API 的结构和行为，然后生成相应的文档。
- 一致性和标准化：通过使用 Swagger，团队可以确保 API 的设计和实现符合一致的标准和规范，从而提高代码质量和可维护性。
- 协作：Swagger 提供了一个统一的 API 描述格式（OpenAPI Specification），使得开发团队、测试团队和文档团队可以更好地协作。
而对于我们的研发团队来说，swagger可以清晰的定义接口，即是代码也是文档，大大提升了前后端沟通的效率，团队内协作的效率！
而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：初始化项目
创建一个新的Gin项目或在现有项目中添加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文档。
