Go gin框架使用swagger生成API文档

博主： 🍁Fall In Dream🍃
发布时间：2021 年 03 月 15 日
1259 次浏览
4148字数
分类： Go 技术

> swagger是一个golang版本的swagger文档生成器，提供了native code包装器，并且支持主流的web框架包裹器
>
> github 地址：https://github.com/swaggo/gin-swagger

### 下载安装 swag

```shell
$ go get -u github.com/swaggo/swag/cmd/swag
```

### 在Go项目根文件夹中运行Swag

> 在`main.go`所在目录执行 `swag init`, -g 参数是输出详细信息
>
> 执行后，会生成docs/doc.go以及docs/swagger.json,docs/swagger.yaml

```shel
$ swag init
```

![在这里插入图片描述](https://img-blog.csdnimg.cn/20200930165802317.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjY2MTMyMQ==,size_16,color_FFFFFF,t_70#pic_center)

### 下载gin-swagger

```shell
$ go get -u github.com/swaggo/gin-swagger
$ go get -u github.com/swaggo/files
```

然后在路由文件引入

```go
import (
	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)
```

添加访问文档路由

```go
// swage 文档访问路由\n
eng := gin.Default()
eng.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
```

### 注释参数

- 注释详细格式参考：https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html
- 主程序注释(main.go)

```go
  // @title Golang Esign API
  // @version 1.0
  // @description  Golang api of demo
  // @termsOfService http://github.com

// @contact.name API Support
  // @contact.url http://www.cnblogs.com
  // @contact.email ×××@qq.com

//@host 127.0.0.1:8081
  func main() {
  }
  ```
- 控制器注释（congroller.go）

- Get 参数方法

```go
    type GetOperationLogListResponse struct {
        List  *[]model.OperationLog `json:"list"`
        Total int                   `json:"total"`
    }

// @Title 应用中心操作日志
    // @Author mengyilingjian@outlook.com
    // @Description 获取应用中心操作日志
    // @Tags operationlog
    // @Param Authorization	header string true "Bearer 31a165baebe6dec616b1f8f3207b4273"
    // @Param route formData string false "路由"
    // @Param operator formData string false "操作者"
    // @Param operation_type formData string false "操作类型 1 新增、2 删除、3 更新"
    // @Param description formData string false "操作描述"
    // @Param start_time formData string false "开始时间"
    // @Param end_time formData string false "结束时间"
    // @Param page formData string true "页数"
    // @Param size formData string true "数据条数"
    // @Success 200 {object} GetOperationLogListResponse
    // @Router	/api/v1/app/operationlog/appcenter [get]
    func GetOperationLogList(c *gin.Context) {

}
    ```

以上生成文档格式如下： ![在这里插入图片描述](https://img-blog.csdnimg.cn/20200930165902928.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjY2MTMyMQ==,size_16,color_FFFFFF,t_70#pic_center)
    ![示例](https://img-blog.csdnimg.cn/20200930165941708.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjY2MTMyMQ==,size_16,color_FFFFFF,t_70#pic_center)
  - Post 参数方法

```go
    ReleaseTemplateAdd struct {
        Name               string `json:"name"`
        DeployEnv          string `json:"deploy_env"`
        GitlabType         int    `json:"gitlab_type"`
        GitlabBranchName   string `json:"gitlab_branch_name"`
        IsAutoRelease      int    `json:"is_auto_release"`
        Description        string `json:"description"`
        GitlabCITemplateID int32  `json:"gitlab_ci_template_id"`
        GitlabID           uint32 `json:"gitlab_id"`
    }
    // @Title 新增模版
    // @Author mengyilingjian@outlook.com
    // @Description 新增模版
    // @Tags release template
    // @Param Authorization	header	string true "Bearer 31a165baebe6dec616b1f8f3207b4273"
    // @Param body body	ReleaseTemplateAdd true "JSON数据"
    // @Success 200 {object} handler.ReportJSONResult
    // @Router	/api/v1/release/template/add <div class="preview">
<div class="post-inser post box-shadow-wrap-normal">
<a href="" target="_blank" class="post_inser_a no-external-link no-underline-link">

</div>
</div>
</a>

</div>

</div>
    func ReleaseTemplateAdd(c *gin.Context){

}
    ```

以上生成格式文档如下：
    ![示例](https://img-blog.csdnimg.cn/20200930170004291.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjY2MTMyMQ==,size_16,color_FFFFFF,t_70#pic_center)

最后修改：2021 年 03 月 16 日

感谢赏赐的coffee~

发表评论取消回复
来了不说两句？

评论 *

名称 *

🎲

邮箱 *

地址

Go gin框架使用swagger生成API文档

🍁Fall In Dream🍃 • 2021 年 03 月 15 日

> swagger是一个golang版本的swagger文档生成器，提供了native code包装器，并且支持主流的web框架包裹器
>
> github 地址：https://github.com/swaggo/gin-swagger

### 下载安装 swag

```shell
$ go get -u github.com/swaggo/swag/cmd/swag
```

### 在Go项目根文件夹中运行Swag

> 在`main.go`所在目录执行 `swag init`, -g 参数是输出详细信息
>
> 执行后，会生成docs/doc.go以及docs/swagger.json,docs/swagger.yaml

```shel
$ swag init
```

### 下载gin-swagger

```shell
$ go get -u github.com/swaggo/gin-swagger
$ go get -u github.com/swaggo/files
```

然后在路由文件引入

```go
import (
	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)
```

添加访问文档路由

```go
// swage 文档访问路由\n
eng := gin.Default()
eng.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
```

### 注释参数

- 注释详细格式参考：https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html
- 主程序注释(main.go)

```go
  // @title Golang Esign API
  // @version 1.0
  // @description  Golang api of demo
  // @termsOfService http://github.com

// @contact.name API Support
  // @contact.url http://www.cnblogs.com
  // @contact.email ×××@qq.com

//@host 127.0.0.1:8081
  func main() {
  }
  ```
- 控制器注释（congroller.go）

- Get 参数方法

```go
    type GetOperationLogListResponse struct {
        List  *[]model.OperationLog `json:"list"`
        Total int                   `json:"total"`
    }

}
    ```

</div>
</div>
</a>

</div>

</div>
    func ReleaseTemplateAdd(c *gin.Context){

}
    ```

Go gin框架使用swagger生成API文档

发表评论取消回复
来了不说两句？

GitKraken破解及汉化教程，支持最新版本。

PHP -- Easyswoole验证器Validat自定义错误信息

海南记忆

红色-电钢琴-二手-转卖

golang-nsq高性能消息队列

子系统命令、备份及还原

【Go Time】Go语言 make 与new 的区别

Go gin框架使用swagger生成API文档

Yii2 升级后运行报错 Call to a member function validateCsrfToken() on array

数据库之mysql

Go gin框架使用swagger生成API文档

发表评论 取消回复 来了不说两句？

Go gin框架 使用swagger生成API文档

发表评论取消回复
来了不说两句？

Go gin框架使用swagger生成API文档