『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. 做法
- 要知道 swagger 注释的语法
- 如何在 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 文档。
全文完，谢谢，我是谢伟，再会。
