swaggo/swag

这是什么？

核心功能

• 01生成 JSON、YAML 格式的 Swagger 2.0 规范以及 Go 的 docs 包。
• 02通过放在 Go 处理函数上方的注释标注来描述接口。
• 03支持请求参数、响应、请求头、安全定义和标签分组。
• 04读取结构体字段标签，用于示例值、校验规则和枚举。
• 05为 Gin、Echo、Fiber、net/http、chi 等框架提供 Swagger UI 中间件。
• 06提供 swag fmt 命令，用于格式化标注注释。

适用场景

• 为 Go REST 服务生成接口文档，无需手工维护单独的 OpenAPI 文件。
• 为 Gin 或 Echo 后端提供交互式 Swagger UI 页面。
• 在 CI 构建中让接口文档与处理函数代码保持同步。

快速上手

1. 1

   使用 Go 安装 swag 命令行工具

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

   在 Go 源代码注释中添加 API 注解

3. 3

   在包含 main.go 的项目根目录运行 swag init 生成文档

   swag init

使用前须知

• !仅生成 Swagger 2.0 文档，不支持 OpenAPI 3.x。
• !需要在 Go 注释中编写注解，并在修改后重新生成文档。

标签

常见问题

swag 是什么？

从 Go 源码注释中的声明式标注自动生成 Swagger 2.0 接口文档的工具。 Swag 解析 Go 代码中按约定格式书写的注释，包括处理函数和结构体定义，并生成 Swagger 2.0 文档，输出 swagger.json、swagger.yaml 和 docs.go。开发者在处理函数上方添加 @Summary、@Param、@Success、@Router 等标注，运行 swag init 即可重新生成规范文件。

swag 可以免费使用吗？用的什么许可证？

swag 以 MIT 许可证开源。用于商业产品前，请先确认许可证条款。

swag 还在维护吗？

半年内有更新。swag 最近一次提交是在 2026年9月30日。

swag 适合用来做什么？

为 Go REST 服务生成接口文档，无需手工维护单独的 OpenAPI 文件。 为 Gin 或 Echo 后端提供交互式 Swagger UI 页面。 在 CI 构建中让接口文档与处理函数代码保持同步。

swag 怎么安装和运行？

使用 Go 安装 swag 命令行工具: go install github.com/swaggo/swag/cmd/swag@latest 在 Go 源代码注释中添加 API 注解 在包含 main.go 的项目根目录运行 swag init 生成文档: swag init

在哪里获取 swag？

源代码和安装说明在 GitHub 上：https://github.com/swaggo/swag