【Gin实战系列】使用 swagger 文档

## 简述

写后端接口离不开 api 文档，目前 api 文档有两种方式：

1. 程序生成
2. 人工维护

人工维护和程序生成，两种方式的 api 文档方式，优缺点不言而喻了。相信基本都会通过程序生成 api 文档，下面介绍一下在 gin 钟整合 swagger 做为 api 文档。

swagger将注释添加到API源代码中，请参阅声明性注释格式。然后通过二进制命令生成接口文档。

## swagger 整合
### 步骤
#### 1.下载 go 的 swagger 包

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

#### 2.编写 api 注释

这里使用之前的项目的test方法：

```go

// test api
// @Summary 测试api
// @Description 通过接收username返回字符串
// @ID test-api
// @Accept  x-www-form-urlencoded
// @Produce  json
// @Param username path string true "用户名"
// @Success 200 {object} string
// @Header 200 {string} Token "qwerty"
// @Router /test [get]
func Test(c *gin.Context)  {
	//实例化一个TestRequest结构体，用于接收参数
	testStruct := requests.TestRequest{}

//接收请求参数
	err := c.ShouldBind(&testStruct)

//判断参数校验是否通过，如果不通过，把错误返回给前端
	if err != nil {
		c.JSON(http.StatusOK, gin.H{"error": requests.Translate(err)})
		return
	}
	//调用HelloService
	var service hello.HelloContract

//这里使用的是接口定义了变量
	service = &hello.HelloService{}
	//调用服务的方法处理业务
	result := service.SayHello(testStruct.Username)

//返回响应
	c.JSON(http.StatusOK, gin.H{"data": result})
}
```

登录查看更多内容

【Gin实战系列】使用 swagger 文档

作者

sockstack

许可协议

CC BY 4.0

发布于

2023-09-02

修改于

2023-09-02

尚未登录

专栏目录