0x00 前言
- 面向读者:
第一次在Windows环境构建go开发环境.- 本文目的
学习使用gin进行接口开发, 并为此接口服务添加swagger接口文档功能- 注意:
请自带梯子
0x01 环境
本文开发环境为Windows 7, 所以这里以 win 7 为例进行介绍.
- 下载安装包
首先在官网https://golang.org/dl/, 选择msi安装包.
-
安装
大力双击下载到的安装文件, 我们这里把它安装到D:\go目录
安装 创建工作目录
手动创建目录D:\go_base, 这个目录就是将来go的依赖库下载目录 ,
同时,也是我们添加新项目所在的目录.
这里和
java的工作机制不太一样.
不过感觉这种设定也挺好的,不用"满地图"到处找代码 :-)
- 环境变量设定
GO开头的环境变量如下:
GOARCH=amd64
GOBIN=D:\go\bin
GOOS=windows
GOPATH=D:\go_base
GOROOT=D:\go
配置完成后, 打开一个新的命令行窗口, 能正常执行 go env表示安装配置成功.
- 配置
GoLand
打开Goland的设置画面, 点选并设置GO下面的两个选项:
GOROOT
GOPATH
到这里, 开发环境已经基本配置完成 .
0x02 创建第一个Go版本的api项目
Go语言版本的RestApi框架有很多, 这里我们以https://github.com/gin-gonic/gin 作为学习对象.
- 手动下载
gin依赖项
打开命令行窗口, 执行命令:
go get -u github.com/gin-gonic/gin
执行正常结束后, 会在
%GOPATH%\src\github.com\gin-gonic\gin目录下多出一大票代码.
如你所想, 这个命令, 就是把github上的代码下载到本地了.
one more thing
Go编译成功后, 只有一个执行文件(便于发布?).
因此, 就不难理解 , 为什么下载依赖, 其实就是把依赖的源码给拉下来了.
-
创建项目
创建一个新的Go工程, 注意选择路径为%GOPATH%\src\项目名称
image.png
设置好目录后, 下一步, 就直接到了开发主界面了.
好简洁呀,一个文件都没有 O_O
主界面 编写代码
好吧, 我们还是进入正题, 参考gin官网示例程序,导入测试代码.
我们在项目中手动创建一个main.go文件,内容如下
package main
import "github.com/gin-gonic/gin"
func main() {
r := gin.Default()
r.GET("/ping", func(c *gin.Context) {
c.JSON(200, gin.H{
"message": "pong",
})
})
r.Run() // listen and serve on 0.0.0.0:8080
}
- 运行
一般的, 我们写一个go文件, 如果package main下面, 再有一个func main()的话, 那么这个main()就是程序 的入口了.
我们可以直接在IDE上 轻戳边上的小三角, 启动程序.
- 验证
程序启动后, 我们就可以 访问 http://localhost:8080/ping此接口, 查看效果:
哇, 这代码量, 比
SpringBoot少了不是一点半点啊, 点赞
到这里呢, 框架开发的流程已经走完了, 接下来开发的部分, 参考文档慢慢学习.
0x03 导入 SwaggerUI
作为一个不爱写文档, 又恨别人不写文档的的程序员, 我们当然选择
Swagger来做为接口说明输出啦.
这个神器可是Spring项目的标配了,go开发的接口当然也不能放松要求.
我们使用https://github.com/swaggo/gin-swagger作为 swagger接入方案.
跟上面的流程一样, 我们先下载依赖
go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
go get -u github.com/alecthomas/template
-
开始导入
在项目根目录(main.go所在目录 ) , 执行命令行:swag init,会在项目目录下生成一堆文件.
swag init 修改代码
要增加的代码太零散, 直接上完成代码
其中
DOC主体注释写法参考
https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.htmlAPI上面的注释写法请参考
https://swaggo.github.io/swaggo.io/declarative_comments_format/api_operation.html
package main
import (
"github.com/gin-gonic/gin"
swaggerFiles "github.com/swaggo/files"
"github.com/swaggo/gin-swagger"
_ "hello_gin/docs"
)
// @title 国服最坑开发
// @version 1.0.1
// @description 神奇的API.
// @termsOfService http://swagger.io/terms/
// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @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 /
func main() {
r := gin.Default()
url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // The url pointing to API definition
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))
r.GET("/ping", pong)
r.Run() // listen and serve on 0.0.0.0:8080
}
// Ping Pong
// @Summary Ping Pong
// @Description get string by ID
// @Tags 健康检测
// @Produce json
// @Success 200
// @Router /ping [get]
func pong(ctx * gin.Context) {
ctx.JSON(200, gin.H{
"message": "pong",
})
}
注意
每次修改注释后, 都要执行swag init, 然后再启动服务进行验证
- 验证
启动服务后,打开网页 http://localhost:8080/swagger/index.html, 查看效果:
0x04 后记
为什么要搞
golang?
最近线上发现在用java作计算密集型的操作时, 时间消耗有点大.
就想着是否要另外一种语言来作替代实现.
生命不息, 折腾不止, go起来
体验:
这一篇只是刚刚开始, 关于
swagger熟练使用, 还有很长路要走.
对比java版的swagger, 感觉java的好像更简单一点?
不不不, 只是自己还没熟练吧, 哈哈
