转载

Golang-01 windows 环境 gin + swagger

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 表示安装配置成功.

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 编译成功后, 只有一个执行文件(便于发布?).

因此, 就不难理解 , 为什么下载依赖, 其实就是把依赖的源码给拉下来了.

创建项目
创建一个新的 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.html
API 上面的注释写法请参考
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 , 然后再启动服务进行验证