国外网站案例,电商网站模板免费,企业网站服务器,建筑网片铁丝规格一. 为什么后端需要配置Swagger 在前后端分离的项目中#xff0c;后端配置swagger可以很好的帮助前端人员了解后端接口参数和数据传输。 Swagger是一个用于设计#xff0c;构建和文档化API的开源框架。在Go语言中#xff0c;Swagger可以帮助后端开发人员快速创建和定义RESTf…一. 为什么后端需要配置Swagger 在前后端分离的项目中后端配置swagger可以很好的帮助前端人员了解后端接口参数和数据传输。 Swagger是一个用于设计构建和文档化API的开源框架。在Go语言中Swagger可以帮助后端开发人员快速创建和定义RESTful API并提供自动生成接口文档的功能这些文档包含了API的详细信息以及如何使用他们的说明。 RESTful API RESTful是一个网络应用程序的设计风格基于HTTP协议。使用XML或JSON格式定义统一标准接口。强调资源统一接口URL和无状态的设计风格。 总的来说RESTful就是一个资源定位资源操作的风格。不是标准也不是协议只是一种风格。 资源互联网所有的事务都可以抽象为资源资源操作分为POSTDELETEPUTGET四种方法使用不同的方法对资源进行操作(增删改查) 传统风格与RESTful风格对比 传统风格通过不同的参数实现不同的效果方法单一。 http://127.0.0.1/item/queryItem.action?id1 查询,GET http://127.0.0.1/item/saveItem.action 新增,POST http://127.0.0.1/item/updateItem.action 更新,POST http://127.0.0.1/item/deleteItem.action?id1 删除,GET或POST RESTful方式操作资源通过不同的请求方式来实现不同的效果。 如下请求资源地址相同但是功能不同。 http://127.0.0.1/item/1 查询,GET http://127.0.0.1/item 新增,POST http://127.0.0.1/item 更新,PUT http://127.0.0.1/item/1 删除,DELETE 现在的网络上基本上全是RESTful风格。 二. 基本使用 2.1 安装 安装最新swagger库
go install github.com/swaggo/swag/cmd/swaglatest测试是否安装成功 2.2 使用步骤 以Gin框架为例需要用到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.3 添加注释 在程序入口main函数上以注释的方式写下项目相关介绍信息。
// title Swagger Example API
// version 1.0
// description this is a sample server celler server
// termsOfService https://www.swagger.io/terms/// contact.name 氷
// contact.url http://www.swagger.io/support
// contact.email abc.xyzqq.com// 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 测试sayHello
// Description 向你说hello
// Tags 测试
// Accept json
// Param name query string true 人名
// Success 200 {string} string {msg: hello wy}
// Failure 400 {string} string {msg: who are you}
// Router /hello [get] 通用API信息 注释描述AcceptAccept字段仅适用于带有request body的请求例如POST、PUT和PATCH。只有使用这些请求方法的接口才需要定义接收的 MIME 类型列表。Produce定义接口返回的 MIME 类型列表。 MIME类型
别名MIME Typejson application/jsonxml text/xmlplain text/plainhtml text/htmlmpfd multipart/form-datax-www-form-urlencodedapplication/x-www-form-urlencodedjson-apiapplication/vnd.apijsonjson-streamapplication/x-json-streamoctet-stream application/octet-streampng image/pngjpeg image/jpeggif image/gif
API操作
Summary 接口功能的简要概述。Description 接口的详细说明。Tags 接口的标签列表可以有多个标签每个标签用英文的逗号分隔。这样接口会按照标签进行分类。Param 接口接收的数据参数用空格分隔。参数分别是“参数名” “参数类型” “数据类型” “是否必须” “参数的描述” “其它属性”。Success 接口的成功响应语法格式“响应的状态码” “响应参数类型” “响应数据类型” “描述信息”。Failure 接口的故障响应语法格式“响应的状态码” “响应参数类型” “响应数据类型” “描述信息”。Response 与Success和Failure的作用相同。Router 接口的路由定义用空格隔开路径和请求方法。 path [httpMethod]Security 定义接口的安全性 Param 参数类型
query该类型参数直接拼接在URL中。URL中后面的参数path该类型参数一般组合在URL中。如/api/v1/:idheaderbodyformData该类型参数一般是POSTPUT方法所用。
数据类型
string (string)integer (int, uint, uint32, uint64)number (float32)boolean (bool)object (struct) 如果你是上传文件可以使用file但参数类型一定是formData
其它属性 除了上面这些属性外我们还可以为该参数填写一些额外的属性如枚举默认值值范围等。
枚举
// Param enumstring query string false string enums Enums(A, B, C)
// Param enumint query int false int enums Enums(1, 2, 3)
// Param enumnumber query number false int enums Enums(1.1, 1.2, 1.3)值添加范围
// Param string query string false string valid minlength(5) maxlength(10)
// Param int query int false int valid mininum(1) maxinum(10)设置默认值// Param default query string false string default default(A) Success/Failure 响应状态码也就是200400500这些
响应参数类型整个数据类型。string表示字符串object表示自定义类型anrry表示数组
响应数据类型具体当个数据的类型。
描述信息其它说明。
例如
表示响应状态码200 响应是参数字符串类型数据也是字符串类型
// Success 200 {string} string表示响应状态码200 响应是参数自定义类型数据也是自定义类型为main包中的File类型
// Success 200 {object} main.File表示响应状态码200 响应是参数数组类型数据类型表示数组中单个元素类型为main包中的File类型
//Success 200 {anrry} main.File表示响应状态码200 响应是参数字符串类型数据类型字符串表示的是json类型// Success 200 {string} json Router 格式 不需要加基础路径。
//Router /path/to/handle [http方法] 2.4 测试示例
自动生成swagger文档
package mainimport (net/httpgithub.com/gin-gonic/ginswaggerFiles github.com/swaggo/filesginSwagger github.com/swaggo/gin-swagger
)// title Swagger Example API
// version 1.0
// description this is a sample server celler server
// termsOfService https://www.swagger.io/terms/// contact.name 氷
// contact.url http://www.swagger.io/support
// contact.email abc.xyzqq.com// 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()//注册swagger api相关路由r.GET(/swagger/*any, ginSwagger.WrapHandler(swaggerFiles.Handler))v : r.Group(/api/v1){v.GET(/hello, helloHandler)}r.Run()
}// helloHandler
// Summary 测试sayHello
// Description 向你说hello
// Tags 测试
// Accept json
// Param name query string true 人名
// Success 200 {string} string {msg: hello wy}
// Failure 400 {string} string {msg: who are you}
// Router /hello [get]
func helloHandler(c *gin.Context) {name : c.Query(name)if name {c.JSON(http.StatusBadRequest, gin.H{msg: who are you})return}c.JSON(http.StatusOK, gin.H{msg: hello name})
}在main.go目录下执行swag init就可以当前目录下自动生成文档 然后我们在main.go中导入自动生成的docs包运行
package mainimport (net/httpgithub.com/gin-gonic/ginswaggerFiles github.com/swaggo/filesginSwagger github.com/swaggo/gin-swagger_ sample-app/swagger/docs
)//... 浏览器打开http://127.0.0.1:8080/swagger/index.html我们可以看到对于接口文档。 介绍 点击Try it out就可以进行测试 2.5 多个tags
package mainimport (net/httpgithub.com/gin-gonic/ginswaggerFiles github.com/swaggo/filesginSwagger github.com/swaggo/gin-swagger_ sample-app/swagger/docs
)// title Swagger Example API
// version 1.0
// description this is a sample server celler server
// termsOfService https://www.swagger.io/terms/// contact.name 氷
// contact.url http://www.swagger.io/support
// contact.email abc.xyzqq.com// 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()//注册swagger api相关路由r.GET(/swagger/*any, ginSwagger.WrapHandler(swaggerFiles.Handler))v : r.Group(/api/v1){v.GET(/hello, helloHandler)v.GET(/hello1, helloHandler1)v.GET(/load, loadHandler)}r.Run()
}// Summary 测试sayHello
// Description 向你说hello
// Tags 测试
// Accept json
// Param name query string true 人名
// Success 200 {string} string {msg: hello wy}
// Failure 400 {string} string {msg: who are you}
// Router /hello [get]
func helloHandler(c *gin.Context) {name : c.Query(name)if name {c.JSON(http.StatusBadRequest, gin.H{msg: who are you})return}c.JSON(http.StatusOK, gin.H{msg: hello name})
}// Summary 测试sayHello other
// Description 向你说hello
// Tags 测试
// Accept json
// Param name query string true 人名
// Success 200 {string} string {msg: hello wy}
// Failure 400 {string} string {msg: who are you}
// Router /hello1 [get]
func helloHandler1(c *gin.Context) {name : c.Query(name)if name {c.JSON(http.StatusBadRequest, gin.H{msg: who are you})return}c.JSON(http.StatusOK, gin.H{msg: hello name})
}// Summary 加载账号密码
// Description 加载账号密码
// Tags 加载
// Accept json
// Param id query string true 账号
// Param passwd query string true 密码
// Success 200 {string} json {msg: id:asd passwd:2123}
// Failure 400 {string} json {msg: 账号或密码错误}
// Router /load [get]
func loadHandler(c *gin.Context) {name : c.Query(id)passwd : c.Query(passwd)if name || passwd {c.JSON(http.StatusBadRequest, gin.H{msg: 账号或密码错误})return}c.JSON(http.StatusOK, gin.H{msg: id: name passwd: passwd})
}重新在命令行输入swag init。生成swag文档运行main.go。访问为http://127.0.0.1:8080/swagger/index.html 三. 优化 swagger文档只是我们测试的时候需要当我们产品上线后接口文档是不应该给用户的并且带有接口文档的包会大很多(swaggo是直接build到二进制中的) 想处理这种情况我们可以在编译的时候优化一下。比如利用build -tags来控制是否编译文档。 go build -tags 是一个 Go 语言的命令行选项用于在构建过程中启用或禁用特定的编译标签。这些标签通常用于控制代码的特定行为例如启用或禁用某些功能、优化等 比如下面表示tag1 和 tag2 是你想要启用的标签。你可以根据需要添加更多的标签用空格分隔。 go build -tags tag1 tag2 在你的 Go 代码中你可以使用 // build 注释来指定哪些文件应该在特定的标签下编译。 在main.go声明swagHandler变量并在该参数不为空时才加入路由。编译带docs标签的swagHandler才不会为空。才可以使用swagger接口文档。 docs.go
//go:build docs
// build docspackage mainimport (_ sample-app/swagger/docsswaggerFiles github.com/swaggo/filesginSwagger github.com/swaggo/gin-swagger
)func init() {swagHandler ginSwagger.WrapHandler(swaggerFiles.Handler)
} main.go
package mainimport (net/httpgithub.com/gin-gonic/gin_ sample-app/swagger/docs
)var swagHandler gin.HandlerFunc// title Swagger Example API
// version 1.0
// description this is a sample server celler server
// termsOfService https://www.swagger.io/terms/// contact.name 氷
// contact.url http://www.swagger.io/support
// contact.email abc.xyzqq.com// 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()//不为空才会加入swagger路由if swagHandler ! nil {//注册swagger api相关路由r.GET(/swagger/*any, swagHandler)}v : r.Group(/api/v1){v.GET(/hello, helloHandler)}r.Run()
}// Summary 测试sayHello
// Description 向你说hello
// Tags 测试
// Accept json
// Param name query string true 人名
// Success 200 {string} string {msg: hello wy}
// Failure 400 {string} string {msg: who are you}
// Router /hello [get]
func helloHandler(c *gin.Context) {name : c.Query(name)if name {c.JSON(http.StatusBadRequest, gin.H{msg: who are you})return}c.JSON(http.StatusOK, gin.H{msg: hello name})
}带标签比不带标签编译出来的文件大小大很多。
