swagger-gin

### 如何在 Gin 框架中集成 Swagger 实现 API 文档自动生成 要在 Go 的 Gin 框架中集成 Swagger 并实现 API 文档的自动生成，可以按照以下方法操作： #### 安装依赖库 首先需要安装 `swag` 工具以及其对应的包。可以通过运行以下命令来完成安装： ```bash go get -u github.com/swaggo/files go get -u github.com/swaggo/gin-swagger go install github.com/swaggo/swag/cmd/swag@latest ``` 这些工具提供了必要的支持功能用于生成和展示 Swagger 文档。 #### 初始化项目并配置路由 创建一个新的 Go 文件作为入口文件（例如 `main.go`），初始化 Gin 路由器，并引入 Swagger 所需的功能模块。以下是基本代码结构的一个例子： ```go package main import ( "github.com/swaggo/files" "github.com/swaggo/gin.swagger" gin "github.com/gin-gonic/gin" ) // @title Gin-Swagger Example API // @version 1.0 // @description This is a sample server Petstore server. func main() { r := gin.Default() url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // The url pointing to API definition r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url)) r.Run(":8080") } ``` 上述代码设置了 `/swagger/*any` 路径指向 Swagger UI 页面[^3]。 #### 编写注解以定义 API 接口 为了使 Swag 自动解析接口信息，在每个 HTTP 方法上都需要添加特定格式的注释。下面是一个简单的 GET 请求示例： ```go // GetUser godoc // @Summary Get user by ID // @Description get user by ID // @ID get-user-by-id // @Accept json // @Produce json // @Param id path int true "User ID" // @Success 200 {object} model.User // @Router /users/{id} [get] func GetUser(c *gin.Context) { id := c.Param("id") c.JSON(200, gin.H{"user": id}) } ``` 通过这样的方式标记每一个控制器函数，则可以在后续阶段被正确识别出来形成完整的文档内容[^2]。 #### 运行 swag init 命令生成文档 当所有的接口都已适当标注之后，执行如下命令即可生成静态 HTML/CSS/JS 文件连同 JSON/YAML 格式的 OpenAPI Specification 数据一起打包到项目的指定目录下： ```bash swag init --generalInfo ./main.go ``` 此过程会读取源码中的特殊注释并将它们转换成标准化的形式供前端界面渲染使用[^1]。 完成后访问 http://<your-domain>:port/swagger/index.html 即可查看实时更新后的在线版交互式 API 参考手册！ ---