大橙子网站建设,新征程启航

为企业提供网站建设、域名注册、服务器等服务

gin集成Swagger-创新互联

前言

一个好的项目工程,必然离不开一个好的 API 文档,如果要自己编写 API 文档,维护起来比较困难,而且难以保证一致性,因此我们要自动生成在线接口文档。

珠海ssl适用于网站、小程序/APP、API接口等需要进行数据传输应用场景,ssl证书未来市场广阔!成为成都创新互联的ssl证书销售渠道,可以享受市场价格4-6折优惠!如果有意向欢迎电话联系或者加微信:18982081108(备注:SSL证书合作)期待与您的合作!swaggo

swagger 在 java 里面,是一个非常流行的 api 组件,他们维护了 go 版本 swaggo,
可以通过 Swagger 2.0 自动生成RESTful API 文档。
swaggo 项目链接

安装 下载代码
# 最新版本
go get -u github.com/swaggo/swag/cmd/swag

# 可以加上版本号
go get -u github.com/swaggo/swag/cmd/swag@v1.8.8
另外还需要下载两个包
# gin-swagger 中间件
go get github.com/swaggo/gin-swagger

# swagger 内置文件
go get github.com/swaggo/gin-swagger/swaggerFiles
安装到 $PATH

$GOPATHbin目录下面没有swag文件,需要go install

cd $GOPATH/pkg/mod/github.com/swaggo/swag@v1.8.8/cmd/swag
# 安装
go install

$GOROOT/bin没有加入$PATH中,需要将其可执行文件移动到$GOBIN

mv $GOPATH/bin/swag /usr/local/go/bin
检查安装

出现这个情况,说明安装成功了

$ swag -v
swag version v1.8.8
gin 集成 swaggo 编写 api 注释

Swagger 中需要将相应的注释或注解编写到方法上,再利用生成器自动生成说明文件

gin-swagger 给出的范例:

// @Summary Add a new pet to the store
// @Description get string by ID
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string	"ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]

参照Swagger的注解规范和范例去编写

// Register
// @Tags 用户管理
// @Summary 用户注册
// @Param username formData string true "username"
// @Param password formData string true "password"
// @Success 200 {string} json "{"code":"200","msg":"success","data":""}"
// @Router /register [post]
func Register(c *gin.Context) {}
路由

在完成了api注释的编写后,我们需要针对 swagger 新增初始化动作和对应的路由规则,才可以使用。在routers/router.go文件,增加swagger的路由:

func Router() *gin.Engine {r := gin.Default()
	
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))

	return r
}
生成

在项目目录下,执行swag init

2022/12/04 15:27:52 Generate swagger docs....
2022/12/04 15:27:52 Generate general API Info, search dir:./
2022/12/04 15:27:52 create docs.go at  docs/docs.go
2022/12/04 15:27:52 create swagger.json at  docs/swagger.json
2022/12/04 15:27:52 create swagger.yaml at  docs/swagger.yaml

执行完成后会在项目根目录下生成docs目录,里面就是api文档相关的内容

docs/
├── docs.go
└── swagger
    ├── swagger.json
    └── swagger.yaml

可以看一下json的内容,其他的也是一样的,只是格式不同
在这里插入图片描述

查看文档

访问地址

http://127.0.0.1:8080/swagger/index.html

在这里插入图片描述

其他信息

main.go方法上,可以增加一些其他信息,完善项目的信息

// @title Swagger Example API
// @version 1.0
// @description This is a sample server celler server.
// @termsOfService https://github.com/stream108

// @contact.name 一江溪水
// @contact.url https://github.com/stream1080
// @contact.email https://github.com/stream108

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 127.0.0.1:8080
// @BasePath /api/v1

你是否还在寻找稳定的海外服务器提供商?创新互联www.cdcxhl.cn海外机房具备T级流量清洗系统配攻击溯源,准确流量调度确保服务器高可用性,企业级服务器适合批量采购,新人活动首月15元起,快前往官网查看详情吧


网站名称:gin集成Swagger-创新互联
URL网址:http://dzwzjz.com/article/ddoces.html
在线咨询
服务热线
服务热线:028-86922220
TOP