什么是swagger

Swagger 是一个用于设计、构建、记录和使用 RESTful Web 服务的工具集。它的主要作用包括：

1. API 文档生成：Swagger 可以自动生成详细的 API 文档，包括每个端点的请求和响应格式、参数、状态码等。这使得开发者和用户可以轻松理解和使用 API。
2. API 测试：Swagger 提供了一个交互式的界面（Swagger UI），用户可以直接在浏览器中测试 API，而无需编写额外的客户端代码。
3. API 设计：Swagger 支持 API 的设计和规范定义，开发者可以使用 Swagger 定义 API 的结构和行为，然后生成相应的文档。
4. 一致性和标准化：通过使用 Swagger，团队可以确保 API 的设计和实现符合一致的标准和规范，从而提高代码质量和可维护性。
5. 协作：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文档。