1a41ece9edd2c77b6d620781788a9608
gin框架构建Api之apidoc:生成 Swagger文档

开发 API 服务,API 文档必不可少,很多人选择手写 API 文档,手写 API 文档有很多问题,比如工作量大、手写容易出错、更新麻烦、格式不固定、维护困难等。所以在实际的开发中,建议自动生成 API 文档。

我们的API 服务器 RESTful 框架采用的是 gin,gin 在 GitHub 上有很多 middleware 可用,其中就有可以自动生成 Swagger 文档的 gin-swagger middleware。

目录

Swagger 配置步骤

因为该包引用 golang.org 中的包,而网络环境原因,一般很难连上 golang.org,所以这里不采用 go get 方式安装。


  • 安装swag命令
$ mkdir -p $GOPATH/src/github.com/swaggo
$ cd $GOPATH/src/github.com/swaggo
$ git clone https://github.com/swaggo/swag
$ cd swag/cmd/swag/
$ go install -v
  • 下载 gin-swagger
$ cd $GOPATH/com.api.com/
$ swag init

$ cd $GOPATH/com.api.com/github.com/swaggo
$ git clone https://github.com/swaggo/gin-swagger
  • 在 router/router.go 中添加 swagger 路由

  • 编写 API 注释,Swagger 中需要将相应的注释或注解编写到方法上,再利用生成器自动生成说明文件
    ```
    // @Summary 视频-web端获取播放地址
    // @Description GetAddressByFileID
    // @Tags video
    // @Accept json
    // @Success 200
    // @Router /video/getAddressByFileId [get]
    func GetAddressByFileID(c *gin.Context) {
    var Video model.Video

    fileID := c.DefaultQuery("file_id", "")
    video := Video.FindVideoByFileID(fileID)

top Created with Sketch.