Gin项目增加接口文档

在 Gin 项目中增加接口文档，通常可以使用 Swagger 这样的工具来生成和展示 API 文档。Swagger 提供了一个简单的方法来描述你的 API，并生成可视化的接口文档。

以下是如何在 Gin 项目中集成 Swagger 并生成 API 文档的步骤：

安装依赖

首先，安装 swag 工具和 Gin 的 Swagger 中间件：

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

生成 Swagger 注释

在你的控制器文件中添加 Swagger 注释，例如 controllers/user.go：

// controllers/user.go
package controllers

import (
	"net/http"
	"github.com/gin-gonic/gin"
)

// GetUsers godoc
// @Summary Get all users
// @Description Get all users
// @Tags users
// @Accept  json
// @Produce  json
// @Success 200 {object} map[string]string
// @Router /users [get]
func GetUsers(c *gin.Context) {
	c.JSON(http.StatusOK, gin.H{
		"message": "Fetching all users",
	})
}

// CreateUser godoc
// @Summary Create a new user
// @Description Create a new user
// @Tags users
// @Accept  json
// @Produce  json
// @Success 200 {object} map[string]string
// @Router /users [post]
func CreateUser(c *gin.Context) {
	c.JSON(http.StatusOK, gin.H{
		"message": "User created successfully",
	})
}

// Unending godoc
// @Summary Unending endpoint
// @Description Unending endpoint
// @Tags default
// @Accept  json
// @Produce  json
// @Success 200 {object} map[string]string
// @Router /unending [get]
func Unending(c *gin.Context) {
	c.JSON(http.StatusOK, gin.H{
		"message": "Unending endpoint",
	})
}

初始化 Swagger

在 main.go 文件中初始化 Swagger：

// main.go
package main

import (
	_ "myapp/docs" // docs is generated by Swag CLI, you have to import it.
	"myapp/routers"

	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

func main() {
	r := routers.SetupRouter()

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

	r.Run(":8080") // Listen and serve on 0.0.0.0:8080
}

生成 Swagger 文档

在项目的根目录下，运行 swag init 生成 Swagger 文档：

swag init

这将在项目根目录下生成一个 docs 目录，里面包含了 swagger.json 和 swagger.yaml 文件。

路由配置

确保在 routers/router.go 文件中设置好路由：

// routers/router.go
package routers

import (
	"github.com/gin-gonic/gin"
	"myapp/controllers"
)

func SetupRouter() *gin.Engine {
	r := gin.Default()

	userRoutes := r.Group("/users")
	{
		userRoutes.GET("/", controllers.GetUsers)
		userRoutes.POST("/", controllers.CreateUser)
	}

	r.GET("/unending", controllers.Unending)

	return r
}

完整示例

以下是所有文件的完整代码：

controllers/user.go

package controllers

import (
	"net/http"
	"github.com/gin-gonic/gin"
)

// GetUsers godoc
// @Summary Get all users
// @Description Get all users
// @Tags users
// @Accept  json
// @Produce  json
// @Success 200 {object} map[string]string
// @Router /users [get]
func GetUsers(c *gin.Context) {
	c.JSON(http.StatusOK, gin.H{
		"message": "Fetching all users",
	})
}

// CreateUser godoc
// @Summary Create a new user
// @Description Create a new user
// @Tags users
// @Accept  json
// @Produce  json
// @Success 200 {object} map[string]string
// @Router /users [post]
func CreateUser(c *gin.Context) {
	c.JSON(http.StatusOK, gin.H{
		"message": "User created successfully",
	})
}

// Unending godoc
// @Summary Unending endpoint
// @Description Unending endpoint
// @Tags default
// @Accept  json
// @Produce  json
// @Success 200 {object} map[string]string
// @Router /unending [get]
func Unending(c *gin.Context) {
	c.JSON(http.StatusOK, gin.H{
		"message": "Unending endpoint",
	})
}

routers/router.go

package routers

import (
	"github.com/gin-gonic/gin"
	"myapp/controllers"
)

func SetupRouter() *gin.Engine {
	r := gin.Default()

	userRoutes := r.Group("/users")
	{
		userRoutes.GET("/", controllers.GetUsers)
		userRoutes.POST("/", controllers.CreateUser)
	}

	r.GET("/unending", controllers.Unending)

	return r
}

main.go

package main

import (
	_ "myapp/docs" // docs is generated by Swag CLI, you have to import it.
	"myapp/routers"

	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

func main() {
	r := routers.SetupRouter()

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

	r.Run(":8080") // Listen and serve on 0.0.0.0:8080
}

访问 Swagger 文档

启动你的应用程序：

go run main.go

然后在浏览器中访问 http://localhost:8080/swagger/index.html，你应该会看到自动生成的 Swagger 接口文档。

通过以上步骤，你已经成功在 Gin 项目中集成了 Swagger，并生成了 API 文档。你可以根据需要扩展和修改这些代码以适应你的项目需求。