go语言gin中文文档 go语言 gin

go语言框架gin之集成swagger

1.先安装Go对应的开源Swagger相关的库

创新互联公司为您提适合企业的网站设计 让您的网站在搜索引擎具有高度排名，让您的网站具备超强的网络竞争力！结合企业自身，进行网站设计及把握，最后结合企业文化和具体宗旨等，才能创作出一份性化解决方案。从网站策划到成都网站制作、网站设计， 我们的网页设计师为您提供的解决方案。

go get github.com/swaggo/swag/cmd/swag

go get github.com/swaggo/gin-swagger

go get github.com/swaggo/files

go get github.com/alecthomas/template

2.验证是否安装成功：swag -v

3.针对接口写入注解

// @Summary 获取多个标签

// @Tags 标签

// @Produce  json

// @Param name query string false "标签名称" maxlength(100)

// @Param state query int false "状态" Enums(0, 1) default(1)

// @Param page query int false "页码"

// @Param page_size query int false "每页数量"

// @Success 200 {object} model.TagSwagger "成功"

// @Failure 400 {object} errcode.Error "请求错误"

// @Failure 500 {object} errcode.Error "内部错误"

// @Router /api/v1/tags [get]

func (t Tag) List(c *gin.Context) {

}

// @Summary 新增标签

// @Tags 标签

// @Produce  json

// @Param name body string true "标签名称" minlength(3) maxlength(100)

// @Param state body int false "状态" Enums(0, 1) default(1)

// @Param created_by body string false "创建者" minlength(3) maxlength(100)

// @Success 200 {object} model.Tag "成功"

// @Failure 400 {object} errcode.Error "请求错误"

// @Failure 500 {object} errcode.Error "内部错误"

// @Router /api/v1/tags [post]

func (t Tag) Create(c *gin.Context) {

}

// @Summary 更新标签

// @Tags 标签

// @Produce  json

// @Param id path int true "标签ID"

// @Param name body string false "标签名称" minlength(3) maxlength(100)

// @Param state body int false "状态 (0为未删除、1为已删除)" Enums(0, 1) default(1)

// @Param modified_by body string true "修改者" minlength(3) maxlength(100)

// @Success 200 {array} model.Tag "成功"

// @Failure 400 {object} errcode.Error "请求错误"

// @Failure 500 {object} errcode.Error "内部错误"

// @Router /api/v1/tags/{id} [put]

func (t Tag) Update(c *gin.Context) {

}

4.针对整个项目进行注解，直接在main方法写入如下注解

//@title 项目名称

//@version 1.0

//@description 这里是描述

func main() {

5.生成执行 swag init

这时会在我项目的docs文件夹下面生成docs.go、swagger.json、swagger.yaml三个文件

6.要在routers中进行默认初始化和注册对应的路由：

r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

同时要引用 _"blog-service/docs" ，不然会报错

7.查看接口文档 ：

8.ok,完成

GO语言（十三）：使用 Go 和 Gin 开发 RESTful API（下）

当客户端在 发出POST请求时/albums，您希望将请求正文中描述的专辑添加到现有专辑数据中。

为此，您将编写以下内容：

1、编写代码

a.添加代码以将专辑数据添加到专辑列表。

在此代码中：

1）用于Context.BindJSON 将请求正文绑定到newAlbum。

2） album将从 JSON 初始化的结构附加到albums 切片。

3）向响应添加201状态代码，以及表示您添加的专辑的 JSON。

b.更改您的main函数，使其包含该router.POST函数，如下所示。

在此代码中：

1）将路径中的POST方法与 /albumspostAlbums函数相关联。

使用 Gin，您可以将处理程序与 HTTP 方法和路径组合相关联。这样，您可以根据客户端使用的方法将发送到单个路径的请求单独路由。

a.如果服务器从上一节开始仍在运行，请停止它。

b.从包含 main.go 的目录中的命令行，运行代码。

c.从不同的命令行窗口，用于curl向正在运行的 Web 服务发出请求。

该命令应显示添加专辑的标题和 JSON。

d.与上一节一样，使用curl检索完整的专辑列表，您可以使用它来确认添加了新专辑。

该命令应显示专辑列表。

当客户端向 发出请求时GET /albums/[id]，您希望返回 ID 与id路径参数匹配的专辑。

为此，您将：

a.在您在上一节中添加的函数下方postAlbums，粘贴以下代码以检索特定专辑。

此getAlbumByID函数将提取请求路径中的 ID，然后找到匹配的专辑。

在此代码中：

（1）Context.Param用于从 URL 中检索id路径参数。当您将此处理程序映射到路径时，您将在路径中包含参数的占位符。

（2）循环album切片中的结构，寻找其ID 字段值与id参数值匹配的结构。如果找到，则将该album结构序列化为 JSON，并将其作为带有200 OK HTTP 代码的响应返回。

如上所述，实际使用中的服务可能会使用数据库查询来执行此查找。

（3）如果找不到专辑，则返回 HTTP 404错误。

b.最后，更改您的main，使其包含对router.GET的新调用，路径现在为/albums/:id ，如以下示例所示。

在此代码中：

（1）将/albums/:id路径与getAlbumByID功能相关联。在 Gin 中，路径中项目前面的冒号表示该项目是路径参数。

a.如果服务器从上一节开始仍在运行，请停止它。

b.在包含 main.go 的目录中的命令行中，运行代码以启动服务器。

c.从不同的命令行窗口，用于curl向正在运行的 Web 服务发出请求。

该命令应显示您使用其 ID 的专辑的 JSON。如果找不到专辑，您将收到带有错误消息的 JSON。

恭喜！您刚刚使用 Go 和 Gin 编写了一个简单的 RESTful Web 服务。

本节包含您使用本教程构建的应用程序的代码。

Go Web 框架 Gin 实践8—为它加上Swagger，帅帅的文档

一个好的 API's，必然离不开一个好的API文档

要开发纯手写 API 文档，不存在的 :=)

项目地址：

1、go get

若 $GOPATH/bin 没有加入$PATH中，你需要执行将其可执行文件移动到$GOBIN下

2、gopm get

该包有引用golang.org上的包，若无科学上网，你可以使用 gopm 进行安装

同理将其可执行文件移动到$GOBIN下

注：三个包都有一定大小，安装需要等一会或要科学上网

编写API注释

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

gin-swagger 给出的范例：

我们可以参照 Swagger 的注解规范和范例去编写

详细的注解请参见 go-gin-example。以确保获取最新的 swag 语法

我们进入到gin-blog的项目根目录中，执行初始化命令

完毕后会在项目根目录下生成docs

docs/

├── docs.go

└── swagger

├── swagger.json

└── swagger.yaml

我们可以检查 docs.go 文件中的 doc 变量，详细记载中我们文件中所编写的注解和说明

大功告成，访问一下 ， 查看 API 文档生成是否正确。是不是很帅？

本系列示例代码

Windows 下安装 Gin 框架

本文主要讲述一下 Windows 下安装 Gin 框架以及遇到的一些坑。安装前请先确保已安装配置好 go 的语言环境。

官方安装地址如下（请先往下看）：

Gin中文文档

1.添加两个环境变量，否则 go get 命令会很慢，请参考如下网站：

GoProxy 中国

先设置一下代理，添加两个环境变量，如下：

2.配置 Goland ，本人使用的开发工具是 Goland ,以下配置均以 Goland 开发工具为例。

这个操作的目的是让我们可以在任意的位置创建我们的项目，而不用拘泥于 GOPATH 目录下。

创建 go 项目的方式有两种：

方式一：

此时会在项目中生成一个 go.mod 文件。

方式二（建议）：

用 Goland 直接创建新项目，依次点击 File-New-project-Go Modules (vgo) ，创建一个新的 go 项目。Location改成自己想要的位置即可。

后续的步骤跟方式一第三步类似，通过 go get 命令获取 Gin 框架源码。

在项目中创建一个 go 文件，这里我就直接拿 Gin 中文文档中给的示例了。然后执行 go run 文件名，浏览器地址栏输入 localhost:8080/ping ，看到输出信息就说明成功了。

补充几个命令：

import "github.com/gin-gonic/gin" 导入 gin 后可以执行如下命令：

本文结束！