『No17: gin-swagger 构建自动化文档』

25.jpg

大家好,我叫谢伟,是一名程序员。

今天的主题:Swagger API 文档

首先问个问题, API 文档重不重要?

重要,前后端的交互一般流程是这样的,后端暴露出API后,交给前端,前端根据API的响应,编写前端页面,一定程度上API 是前后端的交互桥梁。

所以, 我觉得 API 文档很重要。

那么API 文档主要要包含哪些内容?

  • 路由:包括路径参数、请求参数、还是请求体参数
  • 动作:HTTP 请求动作,GET、POST、DELETE、PUT
  • 响应:请求之后的返回值包含哪些信息,一般是JSON

之前我也写过使用Beego 构建API 文档,现在发现Beego 体量太大了。稍有点需求就需要更改。

所以,我不太喜欢体量大的框架。

回顾下传统的做法是编写 swagger.yml 或者 swagger.json 文件。

beego API 自动化文档的做法是编写注释,注释内包含全局信息或者编写应用注释

今天介绍的是 gin 框架 和 gin-swagger 自动构建 API 文档。

手法和 beego 构建自动化API文档一样。编写全局信息和编写应用注释。


1. doc

2. 做法

  1. 要知道 swagger 注释的语法
  2. 如何在 gin 内怎么使用

注释语法这个,全靠查文档。对着文档来。

当然我觉得最好的方法是什么呢,是模仿,找一个别人已经写好的,修修改改,看看能不能编译通过,编译通过后是不是你预期的结果。不是的话,继续修修改改,再编译,再看是不是你希望的结果。如此反复。

效果图:


swagger.png

第一步:编写全局信息注释,在主函数上编写

格式:// @param info


// @title Swagger Example API12222
// @version 1.0
// @description This is a sample server Petstore server.
// @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 petstore.swagger.io
// @BasePath /v1
func main() {
    r := gin.Default()
    r.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    r.GET("/hello/:name", Name)
    r.Run()
}
r.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

这个路由和响应需要有,路由随便的定义,但我觉得我这种方式一目了然,知道是文档。

其他注释对照着参考文档即可。

第二步:编写应用注释

即在响应函数的上方编写注释

type Message struct {
    MessageInfo string `json:"message"`
}

func (m *Message) Serializer()Message{
    return Message{
        MessageInfo: m.MessageInfo,
    }

}


// Name will print hello name
// @Summary Print
// @Accept json
// @Tags Name
// @Security Bearer
// @Produce  json
// @Param name path string true "name"
// @Resource Name
// @Router /hello/{name} [get]
// @Success 200 {object} main.Message
func Name(c *gin.Context){
    name := c.Param("name")

    if name==""{
        return
    }
    var message Message

    message = Message{
        MessageInfo: fmt.Sprintf("hello %s" ,name),
    }
    c.JSON(http.StatusOK, message.Serializer())
}

这里最好把响应体统一成结构体的形式。即

type Message struct {
    MessageInfo string `json:"message"`
}

func (m *Message) Serializer()Message{
    return Message{
        MessageInfo: m.MessageInfo,
    }

}

第三步:目录下 执行命令


swag init

自动生成 docs 文件夹,内含 swagger.json 、swagger.json 、 docs.go

编译不通过,查看报错信息,修改注释。

第四步:导入生成的 docs 文件


import (
    "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"

    _ "./docs" // docs is generated by Swag CLI, you have to import it.
    "github.com/gin-gonic/gin"
    "net/http"
    "fmt"
)

即这个 ./docs

第五步:go run main.go

访问:http://127.0.0.1:8080/docs/index.html

即可查看 swagger 文档。


全文完,谢谢,我是谢伟,再会。

©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 151,829评论 1 331
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 64,603评论 1 273
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 101,846评论 0 226
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 42,600评论 0 191
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 50,780评论 3 272
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 39,695评论 1 192
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 31,136评论 2 293
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 29,862评论 0 182
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 33,453评论 0 229
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 29,942评论 2 233
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 31,347评论 1 242
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 27,790评论 2 236
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 32,293评论 3 221
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 25,839评论 0 8
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,448评论 0 181
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 34,564评论 2 249
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 34,623评论 2 249

推荐阅读更多精彩内容