Go + swaggo + Swagger 生成api文档

在 Go 语言开发中，如果你使用的是 Swagger 或 OpenAPI 规范来生成 API 文档，你可以使用 swaggo 插件来自动生成这些注释和文档内容。

1. swaggo 插件

swaggo 是一个非常流行的 Go 语言插件，用于生成基于 Swagger 的 API 文档。通过在代码中添加特定格式的注释，swaggo 可以自动为你的 API 生成详细的文档。

安装 swaggo 工具

首先，安装 swaggo 生成器工具：


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

然后，在你的项目中初始化 swaggo：


swag init

在代码中使用 swaggo 注释

类似如下：


// UserBlock 屏蔽用户
// @Summary 屏蔽用户
// @Tags User
// @Accept json
// @Produce json
// @Param userId path int true "用户ID"
// @Param blockUserId path int true "被屏蔽用户ID"
// @Param blockReasonId path int true "屏蔽原因ID"
// @Success 200 {string} string "{"success":true,"data":{},err:nil}"
// @Router /user/block [post]
// @Security Bearer
// @Param Authorization header string true "Bearer token"
func UserBlock(c *gin.Context) {
    // 你的代码逻辑
}

@Summary、@Tags、@Param 等注释会被 swaggo 工具解析，用于生成 Swagger 文档。

通过执行 swag init，会自动生成 docs 目录，包含 Swagger JSON 文件，可以通过 Swagger UI 展示 API 文档。

2. 自动补全插件

Visual Studio Code

如果你使用 Visual Studio Code 作为编辑器，可以安装以下插件来获得更好的注释生成体验：

• Go 插件（官方）：提供 Go 语言的代码补全、静态检查、调试等功能。

• Swagger and OpenAPI editor 插件：帮助自动补全 Swagger 注释和 YAML 文件。

• Swagger Viewer 插件：可以在编辑器中预览 Swagger 文档。

3. 使用 swaggo 自动生成 API 文档

在代码中添加注释后，运行 swag init 命令，会自动生成 Swagger 文档：


swag init

这个命令会在项目根目录下生成 docs 目录，里面包含 Swagger 配置的 JSON 文件。

通过这些工具和插件，你可以轻松地在 Go 项目中生成和管理 API 文档。