go-swagger 使用

1. Download Swag for Go by using:

go get -u github.com/swaggo/swag/cmd/swag

2. Add comments to your API source code, See Declarative Comments Format.

例子：

// @summary 商品搜索（全网、淘宝、京东、拼多多、唯品汇）
// @description 可全网比价，参数p 指定搜索区域
// @param q query string true "关键字"
// @Param p query string false "平台来源"
// @accept json
// @produce  json
// @success 200 {string} string	"ok"
// @failure 400  "We need param [q]!"
// @failure 404 "API not found"
// @router /g/s [get]

3. Download gin-swagger by using:

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

4. router.go 中添加路由

ginSwagger "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"




router.GET("/docs/*any", ginSwagger.DisablingWrapHandler(swaggerFiles.Handler, "SwaggerDisabled")) //从环境变量中获取,来是否启动路由

配置 /docs/*any 表示运行主页 http://localhost:8018/docs/index.html 就可以打开了

5. main函数中添加信息

// @title CPS api
// @version 0.1.0
// @description CPS 项目
// @host localhost:8018
// @contact.url [email protected]
// @contact.name cps team
// @BasePath /api/v1
func main() {

注意： @host 参数在swagger测试页面请求的地址，

@BasePath 也要配置正确

6. 在项目目录中有main.go之下执行,生成swagger文件

swag init

7. 测试了

8. 如何鉴权：

参考： https://www.ctolib.com/swaggo-swag.html

由于我的后端是通过token认证的，所以选择的是apikey

8.1 首先在 main 函数上添加

// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Access-Token

name 表示在header中参数名称

ApiKeyAuth 鉴权CODE 自定义, 使用到这个Header标记的，需要在使用方法上与之对应

8.2 在调用方法上加上需要鉴权标记

// @Security ApiKeyAuth

猜你喜欢