Gin使用swagger生成文档

使用 Swagger 可以让你为 Gin 框架的 API 提供自动生成的 API 文档。通过 Swagger，开发者可以方便地查看、测试和分享 API。以下是如何在 Gin 项目中集成和使用 Swagger 的详细步骤。

1. 安装依赖

首先，安装 swag 工具：

go install github.com/swaggo/swag/cmd/swag@latest

2. 添加 Swag 注释

在你的 Gin 项目中，添加 Swag 注释。这些注释将用于生成 Swagger 文档。

示例 main.go：

package main

import (
    "net/http"
    _ "your_project/docs" // docs is generated by Swag CLI, you have to import it.

    "github.com/gin-gonic/gin"
    swaggerfiles "github.com/swaggo/files"     // swagger embed files
    ginSwagger "github.com/swaggo/gin-swagger" // gin-swagger middleware
)

// PingExample godoc
// @Summary ping example
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} json "{"message": "pong"}"
// @Router /ping [get]
func ping(c *gin.Context) {
    c.JSON(http.StatusOK, gin.H{
        "message": "pong",
    })
}

// @title Gin Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080
// @BasePath /api/v1

func main() {
    r := gin.Default()

    // Swagger endpoint
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    // Simple API endpoint
    r.GET("/ping", ping)

    r.Run(":8080")
}

在这个示例中，添加了 Swagger 注释，包括 API 的标题、版本、描述、联系方式和许可信息。这些信息将显示在 Swagger UI 中。

3. 生成 Swagger 文档

使用 swag 命令生成 Swagger 文档。确保在项目根目录中运行：

swag init

这个命令将生成 docs 目录，包含 docs.go 和 swagger.json 等文件。

4. 启动服务器

启动你的 Gin 服务器：

go run main.go

5. 访问 Swagger UI

打开浏览器，访问以下 URL：

http://localhost:8080/swagger/index.html

你应该会看到自动生成的 Swagger UI，其中包含你定义的 API 及其文档。

6. 完整示例项目结构

假设你的项目结构如下：

my-gin-app/
├── main.go
├── go.mod
├── go.sum
└── docs/
    ├── docs.go
    └── swagger.json

7. 示例代码细节

完整的 main.go 文件：

package main

import (
    "net/http"
    _ "your_project/docs" // docs is generated by Swag CLI, you have to import it.

    "github.com/gin-gonic/gin"
    swaggerfiles "github.com/swaggo/files"     // swagger embed files
    ginSwagger "github.com/swaggo/gin-swagger" // gin-swagger middleware
)

// PingExample godoc
// @Summary ping example
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} json "{"message": "pong"}"
// @Router /ping [get]
func ping(c *gin.Context) {
    c.JSON(http.StatusOK, gin.H{
        "message": "pong",
    })
}

// @title Gin Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080
// @BasePath /api/v1

func main() {
    r := gin.Default()

    // Swagger endpoint
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    // Simple API endpoint
    r.GET("/ping", ping)

    r.Run(":8080")
}

8. 总结

通过上述步骤，你可以在 Gin 项目中集成 Swagger 来自动生成 API 文档。这不仅能提高开发效率，还能使你的 API 更易于使用和分享。

评论