【go语言开发】swagger安装和使用

本文主要介绍go-swagger的安装和使用，首先介绍如何安装swagger，测试是否成功；然后列出常用的注释和给出使用例子；最后生成接口文档，并在浏览器上测试

安装

命令行安装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，博主努力更新中…