『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 文档。


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

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏散尽浮华

进程管理利器-supervisor部署记录

一、简单介绍 supervisor是用来管理进程的一个工具,止于为什么要用supervisor,是因为相对于linux传统的进程管理方式来说,它有很多的优势: ...

3848
来自专栏沈唁志

解决 TP3 框架 引入 Log.class.php 文件报错方法

朋友的这个问题真的很无语,可能会出现在使用 SVN 的情况下,使用 Git 进行团队开发忽略以后是不会出现这种问题的

2521
来自专栏用户2442861的专栏

recv函数说明返回值

客户端的程序连接上服务器后recv函数阻塞接受,有时会返回0,说明接收超时服务器主动断开了连接,需要重新connect服务器,但重新connect时会报“Tr...

4101
来自专栏SDNLAB

SDN开发笔记(一):SDN开发环境的搭建(win7环境)

前言 鉴于网上对于SDN开发相关的资料较少又乱的现状,从这篇文章开始,我将陆续分享我在SDN开发过程中的经验,我的SDN项目开发是基于OpenDaylight的...

4378
来自专栏运维

Nginx1.10.2稳定版本tcp四层负载安装配置过程略解

nginx1.10.2(2016.10.18)是最新稳定版,适合线上运行,最新开发版为1.11.8(2016.12.27)

1261
来自专栏java架构师

老生常谈GET和POST,以备常查

------------------- GET 和 POST 请求的区别 // --TCP/IP 协议详解卷3 13.3.1 报文类型:请求与响应 HTTP ...

3137
来自专栏C/C++基础

DOS常用命令大全

2010-04-17 22:27:19|  分类: 电脑技术 |  标签:dos命令大全 |字号大中小 订阅

2161
来自专栏Java帮帮-微信公众号-技术文章全总结

Web-第七天 HTTP&Tomcat学习

HTTP协议:超文本传输协议(HTTP,HyperText Transfer Protocol)是互联网上应用最为广泛的一种网络协议。用于定义WEB浏览器与WE...

1905
来自专栏python学习指南

python爬虫(六)_urllib2:handle处理器和自定义opener

本文将介绍handler处理器和自定义opener,更多内容请参考:python学习指南 opener和handleer 我们之前一直使用的是urllib...

2848
来自专栏散尽浮华

手动编写的几个简单的puppet管理配置

puppet在自动化配置管理方面有很强大的优势,这里就不做过多介绍了,下面记录下几个简单的puppet管理配置: 一、首先在服务端和客户端安装puppet和fa...

3008

扫码关注云+社区

领取腾讯云代金券