我厌倦了记忆 swaggo 注释顺序，于是我做了这个

Source: Dev.to

介绍

Swaggo 在为 Go API 编写文档方面非常强大，但它的注解参数顺序必须严格遵守，这会带来不少麻烦。每次写类似下面的代码时：

// @Param id query string true "User ID"

你都得记住确切的顺序：name、in、type、required、description。这常常导致错误、拼写错误，以及团队 Slack 上频繁出现的 “顺序到底是怎样的？” 的求助信息。

位置参数的问题

• 记忆负担 – 必须记住每个参数的位置。
• 常见混淆 – 类型和 required 标志经常被调换。
• 静默错误 – 结构体名称的拼写错误（例如 dto.UserReponse）直到运行时才会被发现。
• 上手阻力 – 新成员需要花时间学习顺序，而不是专注于 API 逻辑。

解决方案：具名参数注解

一个 VS Code 插件让你可以使用具名参数来编写 Swaggo 注解：

@Param(name="id", in="query", type=string, required=true, desc="User ID")
@Success(code=200, schema=dto.UserResponse, desc="Success")

插件会实时把这些内容转换为普通的 Swaggo 注释，因此源文件仍然保留标准的 // @Param 语法，只是你编辑的是更易读的具名参数版本。

工作原理

• 无需记忆顺序 – 你可以任意顺序指定键 (name、in、type、required、desc)。
• IDE 辅助 – 注解名称和 Go 类型的自动补全，以及显示生成注释的悬停提示。
• 代码片段 – 快速插入常用模式。
• 实时转换 – 当你输入时，插件会更新底层注释。

示例

具名参数版本（你编辑的内容）

@Summary("Create classroom")
@Tags("classroom", "admin")
@Param(name="body", in="body", type=dto.CreateClassroomRequest, required=true, desc="Classroom creation request")
@Success(code=200, schema=dto.ClassroomResponse, desc="Success")
@Router("/classrooms", "post")
func CreateClassroom(c echo.Context) error {
    // your code
}

生成的 Swaggo 注释（文件中实际保存的内容）

// @Summary Create classroom
// @Tags classroom,admin
// @Param body body dto.CreateClassroomRequest true "Classroom creation request"
// @Success 200 {object} dto.ClassroomResponse "Success"
// @Router /classrooms [post]
func CreateClassroom(c echo.Context) error {
    // your code
}

你只需要编辑第一段代码块，插件会负责转换。

好处

• 减少语法提问 – 新成员不再询问参数顺序。
• 错误更少 – 代码审查中因注解格式错误产生的噪音减少。
• 更好的 IDE 支持 – 自动补全和类型校验帮助提前捕获错误。
• 更易重构 – IDE 能验证注解中引用的 Go 类型是否存在。

安装

在 VS Code Marketplace 中搜索 “Swaggo” 或直接安装：

• Marketplace 链接：
• GitHub 仓库：

限制

• 该插件仅提供编辑器侧的便利功能；它 不会 验证引用的类型是否真实存在。此类验证仍由 Swaggo CLI 完成。
• 目前仅支持 VS Code。若有需求，未来可能会支持其他编辑器。

结论

具名参数注解消除了记忆 Swaggo 位置参数顺序的需求，使得在 Go 中编写 Swagger 文档更快、更清晰，也更不易出错。该插件免费、兼容现有的 Swaggo 工具链，且你的代码保持 100 % 兼容。

欢迎在 GitHub 上提交 issue，提出改进建议或功能需求。祝文档编写愉快！