本文主要介绍go-swagger的安装和使用，首先介绍如何安装swagger，测试是否成功；然后列出常用的注释和给出使用例子；最后生成接口文档，并在浏览器上测试
文章目录
- 安装
- 注释说明
- 常用注释
- 参考例子
- 文档生成
- 格式化文档
- 生成docs.go
- 设置路由访问
- 浏览器访问
安装
命令行安装swagger最新库
go install github.com/swaggo/swag/cmd/swag@latest
其他安装文件
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
# 模版
go get -u github.com/alecthomas/template
swag -v测试swagger是否安装成功：
查看常用命令：
注释说明
常用注释
当使用 Go Swagger 时，可以使用不同的注释标记来描述 API 的各个方面，以便生成符合 OpenAPI 规范的 Swagger 文档。以下是常用的 Swagger 注释说明，列出了所有的注释标记：
-
@Summary：用于描述 API 操作的简要概述。
-
@Description：用于提供对 API 操作的详细描述和说明。
-
@ID：用于指定 API 操作的唯一标识符。
-
@Param：用于描述 API 操作的参数，包括参数名、位置、数据类型、是否必需等信息。
-
@Success：用于描述 API 操作的成功响应，包括状态码、响应数据结构等信息。
-
@Failure：用于描述 API 操作的失败响应，包括状态码、响应数据结构等信息。
-
@Router：用于指定 API 路由的信息，包括路径、HTTP 方法等。
-
@Accept：用于指定 API 操作支持的请求内容类型。
-
@Produce：用于指定 API 操作产生的响应内容类型。
参考例子
注册：
// Register 用户注册
//
// @Summary 用户注册
// @Produce json
// @Router /api/user/register [post]
// @Param username query string true "用户名"
// @Param password query string true "密码"
// @Param mobile query string true "电话"
func Register(c *gin.Context) {
userName := c.Query("username")
password := c.Query("password")
mobile := c.Query("mobile")
...
}
main.go
// @title code-go api
// @version 1.0
// @description code-go项目swagger api介绍
// @termsOfService http://swagger.io/terms/
// @contact.name 猫哥说
// @contact.url www.maogeshuo.com
// @contact.email support@swagger.io
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host localhost:8080
// @BasePath /
// @securityDefinitions.basic BasicAuth
// @externalDocs.description OpenAPI
// @externalDocs.url https://swagger.io/resources/open-api/
func main() {
...
}
文档生成
格式化文档
swag fmt
生成docs.go
swag init
执行完swag init，会生成圈红区域文件
设置路由访问
参考截图配置路由路径
norm.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
浏览器访问
浏览器输入访问地址：http://localhost:8080/swagger/index.html
欢迎大家访问个人博客网址：https://www.maogeshuo.com，博主努力更新中…
