Golang Swagger集成

如何在Golang项目中集成Swagger自动生成API文档？目前使用gin框架开发RESTful API，想通过Swagger UI展示接口文档，但不知道具体步骤。是否需要安装特定库？配置文件应该如何编写？生成的文档如何与项目代码保持同步？求具体实现方案和最佳实践。

2 回复

Golang集成Swagger推荐使用swaggo工具。安装swag CLI后，通过注释编写API文档，运行swag init生成swagger.json。引入gin-swagger等中间件即可通过浏览器访问API文档。支持路由分组、参数验证等特性。

更多关于Golang Swagger集成的实战系列教程也可以访问 https://www.itying.com/category-94-b0.html


在Golang中集成Swagger（OpenAPI）可以通过 Swaggo 工具实现，它能够自动生成API文档。以下是详细步骤和示例代码：

步骤1：安装Swaggo工具

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

步骤2：安装Gin和Swagger库（以Gin框架为例）

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

步骤3：编写API并添加Swagger注释

在代码中添加Swagger注释（以main.go为例）：

package main

import (
	"github.com/gin-gonic/gin"
	_ "docs" // 自动生成的docs文件夹
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server.
// @host            localhost:8080
// @BasePath        /api/v1
func main() {
	r := gin.Default()

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

	// 示例API路由
	v1 := r.Group("/api/v1")
	{
		v1.GET("/hello", GetHello)
	}
	r.Run(":8080")
}

// GetHello 处理GET请求
// @Summary      返回欢迎信息
// @Description  获取Hello World
// @Tags         example
// @Accept       json
// @Produce      json
// @Success      200  {object}  map[string]string
// @Router       /hello [get]
func GetHello(c *gin.Context) {
	c.JSON(200, gin.H{"message": "Hello, Swagger!"})
}

步骤4：生成Swagger文档

在项目根目录执行：

swag init

这会生成一个docs/文件夹，包含docs.go、swagger.json和swagger.yaml。

步骤5：运行并访问

  1. 启动服务：go run main.go
  2. 浏览器访问：http://localhost:8080/swagger/index.html

注意事项：

  • 注释需严格遵循Swaggo格式（参考官方文档）。
  • 确保导入生成的docs包（如_ "docs"）。
  • 支持Gin、Echo、Net/Http等框架，调整对应Swagger初始化代码即可。

通过以上步骤，即可快速集成Swagger到Golang项目中，实现API文档自动生成和可视化测试。

回到顶部