本文主要介紹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，博主努力更新中…