中年大叔学编程-Gin-Swagger生成API接口文档

最近简单的学习了一下Golang,并且用Gin开发了两个小应用,一个短域名生成,一个微信小程序。感受到了Golang的代码简洁、部署简单、内存占用少、零停机平滑重启等优势。在开发小程序的时候,需要生成接口文档,这里需要用到Gin-Swagger了,所以简单的就来整理一下。

这里我用的环境是:

go version go1.14.6 windows/amd64

GoLand 2020.2.1

gin v1.6.3

swag v1.6.7

这里先用Goland新建一个demo项目吧,在新建的时候,我们最好就要把包的代理地址配置好

这里我们需要安装Gin、swag、gin-swagger、files几个包,可以通过命令的方式

go get -u github.com/gin-gonic/gin

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

go get -u github.com/swaggo/gin-swagger

go get -u github.com/swaggo/files

但是在Goland中,会自动获取复制的连接,然后提醒安装,直接点击相应的按钮即可,非常方便。这里我们新建一个main.go文件,加入如下代码

import (

_ "GinDemo/docs"

"github.com/gin-gonic/gin"

swaggerFiles "github.com/swaggo/files"

ginSwagger "github.com/swaggo/gin-swagger"

)

func main() {

r := gin.New()

// use ginSwagger middleware to

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

r.Run()

}

然后进入Terminal中执行swag init

现在,运行项目(默认8080端口)并访问http://localhost:8080/swagger/index.html

因为现在还没有开发相应的接口,所以什么信息都没有,在开始之前,我们需要先了解一下gin-swagger的注解

@Tags 接口分组,相当于归类

@Summary 接口的简要描述

@Description 接口的详细描述

@Id 全局标识符

@Version 接口版本号

@Accept 发起请求的数据类型

@Produce 接口返回的数据类型

@Param 请求参数描述

@Success 请求成功后返回信息

@Failure 请求失败后返回信息

@Router 请求的路由路径和请求方式。

@contact.name 接口联系人

@contact.url 联系人网址

@contact.email 联系人邮箱

上面就是一些较为基础的参数说明,当然还有一些更加复杂的,比如@security,@in等,这些以后再说吧,我们就可以在相应的Controller方法上加注解了

// @Tags Demo

// @Id 1

// @Summary 接口Demo

// @Description 接口详细描述信息

// @Produce json

// @Param id path int true "ID"

// @Success 200 {string} string

// @Failure 400 {string} string

// @Router /api/v1/demo/{id} [get]

// @contact.name 中年大叔学编程

// @contact.email eyiadmin@163.com

func Demo(c *gin.Context) {

c.JSON(200,"OK!")

}

在main方法中注册路由

r.GET("/api/v1/demo/:id", controller.Demo)

现在,进入Terminal中再次执行swag init并启动,这时候就可以看到对应的内容了

我们来执行一下看看效果

这样一个API接口文档就有了,而且还方便我们调试。

我只是记录我的学习过程,由于书读得少,可能很多地方表述或者是理解得不对,请轻喷并指正。

  • 发表于:
  • 原文链接https://kuaibao.qq.com/s/20200814A072XK00?refer=cp_1026
  • 腾讯「腾讯云开发者社区」是腾讯内容开放平台帐号(企鹅号)传播渠道之一,根据《腾讯内容开放平台服务协议》转载发布内容。
  • 如有侵权,请联系 cloudcommunity@tencent.com 删除。

扫码关注腾讯云开发者

领取腾讯云代金券