云抢购网官方网站,网站代理合作,wordpress提交内容表格,wordpress数据库4.1.14概述
在前后端分离的项目中#xff0c;后端配置swagger可以很好的帮助前端人员了解后端接口参数和数据传输。go-swagger 是一个功能全面且高性能的Go语言实现工具包#xff0c;用于处理Swagger 2.0#xff08;即OpenAPI 2.0#xff09;规范。它提供了丰富的工具集#x…概述
在前后端分离的项目中后端配置swagger可以很好的帮助前端人员了解后端接口参数和数据传输。go-swagger 是一个功能全面且高性能的Go语言实现工具包用于处理Swagger 2.0即OpenAPI 2.0规范。它提供了丰富的工具集帮助开发者在Go环境中解析、生成、验证和操作API描述文件。OpenAPI 2.0 用于生成、描述、调用和可视化RESTful Web服务。它允许你使用YAML或JSON格式定义API接口包括路径、参数、请求方法、响应类型等信息。
特点 定制化支持: 具备强大的自定义能力通过供应商扩展和可自定义模板满足不同需求。 代码生成: 专注于产出语义正确、运行高效的Go代码兼容golint, go vet等工具。
基本使用
安装 go install github.com/swaggo/swag/cmd/swaglatest 安装后通过swag -v 测试是否安装成功 使用步骤
以gin框架为例
1. 需要用到gin-swagger库 go get -u github.com/swaggo/gin-swagger //gin-swagger中间件 go get -u github.com/swaggo/files //swagger嵌入文件 gin-swagger使用步骤
按照swagger要求给接口代码添加声明式注释具体参照声明式注释格式。使用swag工具扫描代码自动生成API接口文档数据使用gin-swagger渲染在线接口文档页面 2. 添加注释
项目添加注释在main函数下添加下面的注释 // 可以修改的swagger文档的标题 // version 版本 // description 这里是swagger中整个项目的描述 // termsOfService https://www.swagger.io/terms/ // contact.name 维护者名字 // contact.url 维护者联系网址 // contact.email 维护者邮件 // 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 title文档标题 version版本 descriptiontermsOfServicecontact.name contact.urlcontact.email都是一些声明可不写。 license是必须的 hostBasePath如果你想直接swagger调试API这两项需要填写正确。前者为服务文档的端口ip。后者为基础路径像我们这里就是/api/v1。 在原文档中还有securityDefinitions.basic , securityDefinitions.apikey等这些都是 用来做认证的。其他的可以看官方文档
函数接口添加注释在代码中处理请求的接口函数(通常位于controller层)按如下方式注释。 // Summary 测试ping // Description ping // Tags 测试 // Accept json // Success 200 {string} string {msg: pong} // Failure 400 {string} string {msg: nonono} // Router /ping [get] 3. 下面直接使用命令初始化我们的swagger文档 swag init 生成 docs文档文档结构如下
docs docs.go swagger.json swagger.yaml
注意我们初始化的时候一定是当前目录中有main.go的文件 不是有main函数的文件
4. 导入刚才的docs包注意是匿名导入
下面是所有方法的基本示例
package mainimport (github.com/gin-gonic/ginswaggerFiles github.com/swaggo/filesginSwagger github.com/swaggo/gin-swagger_ component/swagger/docs)// 可以修改的swagger文档的标题
// version 版本(默认1.0)
// description 这里是swagger中整个项目的描述
// termsOfService https://www.swagger.io/terms/// contact.name 维护者名字
// contact.url http://www.swagger.io/support
// contact.email 维护者邮件// 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
func main() {r : gin.Default()//在代码中处理请求的接口函数(通常位于controller层)按如下方式注释。//注册swagger api相关路由r.GET(/swagger/*any, ginSwagger.WrapHandler(swaggerFiles.Handler))// 设置路由组/api/v1g : r.Group(/api/v1){g.GET(/ping,PingHandler)g.POST(/login,LoginHandler)}r.Run(127.0.0.1:8080)
}// 模型model
type User struct{Username string json:username example:张三Password string json:password example:123456
}// 响应参数模型model
type ResponseParam struct {Code int json:codeMessage string json:messageData *User json:data
}// 接收参数模型model
type RequestParam struct {Username string json:username example:李四Password string json:password example:123456
}// 接收参数模型2model
type RequestParam2 struct {Username string json:username example:李四Password string json:password example:123456UpdateUsername string json:updateusername example:张三UpdatePassword string json:updatepassword example:789100
}// Summary 测试ping// Description ping// Tags 测试1// Accept application/json// Success 200 {string} string {msg: pong}// Failure 400 {string} string {msg: nonono}// Router /ping [get]
func PingHandler(ctx *gin.Context){ctx.JSON(200,gin.H{code: 1000,msg: pong,})
}// Summary 测试login// Description login// Tags 测试2// Accept application/json// Produce application/json// Param Object body RequestParam true 用户信息// Success 200 {object} ResponseParam// Failure 400 {string} string {msg: failed}// Router /login [post]
func LoginHandler(c *gin.Context){user : new(User)err : c.ShouldBindJSON(user)if err ! nil{c.JSON(200,gin.H{code: 5000,msg: user,})}c.JSON(200,gin.H{code: 2000,msg: user,})
}// Summary 删除用户// Description deleteuser// Tags 测试3// Accept application/json// Produce application/json// Param id path int true 用户id// Success 200 {string} string {msg: 该id{{id}}用户已经被注销}// Failure 400 {string} string {msg: 该id不存在}// Router /user [delete]
func DeleteUser(c *gin.Context){// 传来待删除用户的id(路径参数)id : c.Param(id)ok : (id 1)if ok {c.JSON(200,gin.H{code: 5000,msg: (该idid用户不存在),})}c.JSON(200,gin.H{code: 2000,msg: (该idid用户已经被注销),})}//Summary 更新用户信息// Description update// Tags 测试4// Accept application/json// Produce application/json// Param Object body RequestParam2 true 用户更新后信息// Success 200 {object} ResponseParam// Failure 400 {string} string {msg: failed}// Router /update [put]
func UpdateUser(c *gin.Context){}
注意在每次更新接口和注释信息后要重新进行swag init初始化文档
服务启动后访问每个人的端口可能不一样我这里是8080Swagger UIhttp://127.0.0.1:8080/swagger/index.html#/ 在文档中还可以直接进行调试进行接收请求和响应。
在编写声明式注释时需要知道以下东西 常见的声明式注释格式及选项以 Swagger 为例 Summary 格式Summary 简短描述用途用于提供一个简洁的、对 API 接口功能的总结性描述。这个描述应该能够让使用者快速了解接口主要是做什么的。例如Summary 获取用户信息 或者 Summary 删除指定订单。Description 格式Description 详细描述用途提供比 Summary 更详细的关于接口的信息包括接口的业务逻辑、操作细节、特殊情况等内容。比如Description 根据用户ID从数据库中查询用户的详细信息包括姓名、年龄、联系方式等。Tags 格式Tags 标签列表其中标签列表可以是一个或多个用逗号隔开的标签。用途用于对接口进行分类方便在 API 文档中通过标签来组织和查找接口。例如Tags 用户管理,权限管理这样可以将与用户管理相关的接口和权限管理相关的接口通过不同的标签区分开来便于文档管理和查看。Accept 格式Accept 媒体类型列表媒体类型之间可以用逗号隔开。用途指定接口能够接受的请求内容类型。如 Accept application/json,text/plain表明该接口可以接受 JSON 格式和纯文本格式的请求内容。Produce 格式Produce 媒体类型列表用途用于说明接口会产生返回的内容类型。例如Produce application/json意味着这个接口返回的数据格式是 JSON。Param 格式Param 参数名 参数位置 参数类型 是否必填 参数描述参数位置常见类型 path表示参数是在路径中传递的如 /users/{user_id} 中的 user_id。query参数是在查询字符串中例如 /products?categoryelectronics 中的 category。body参数在请求体中一般用于传递较为复杂的数据结构像创建用户时用户信息以 JSON 等格式放在请求体中。用途用于详细描述接口接受的参数包括参数的名称、位置、类型、是否必填以及参数的具体含义等信息。例如Param user_id path int true 用户ID用于唯一标识用户。Success 格式Success 状态码 返回类型 返回描述用途描述接口成功响应时的情况包括返回的状态码、数据类型以及返回内容的简单描述。例如Success 200 {object} UserInfo 成功返回用户的详细信息这里表示接口成功时返回状态码为 200数据类型是一个对象{object}具体类型可能是自定义的结构体等这里假设是 UserInfo并且说明了返回的是用户详细信息。Failure 格式Failure 状态码 返回类型 返回描述用途和 Success 相对应用于描述接口失败时的情况包括可能出现的错误状态码、返回的数据类型如果有返回内容的话以及错误内容的简单描述。例如Failure 404 {string} 用户不存在说明当出现 404 状态码时返回的数据类型可能是一个字符串并且内容是提示用户不存在。Router 格式Router 路径 [方法]用途用于指定接口对应的路由路径和请求方法。例如Router /users/{user_id} [GET]表明这个接口对应的路径是 /users/{user_id}请求方法是 GET用于获取特定用户的信息。 然后需要注意的是为什么你的swagger中有些函数可以出现有些没有出现
一定要注意参数格式
一定要注意参数格式
一定要注意参数格式
