go+swagger项目接口文档生成整理

# 一、前言
1、一些项目的技术文档无法保证实时性，即使当初规则定的再规范也很难在迭代中执行。
2、团队伙伴标准不一,执行不太能够统一
3、额外在postman 或者 apifox接口管理工具中编写文档需要付出额外工作
		
# 二、go如何使用swagger
## 2.1 安装 Go 对应的开源 Swagger 组件库
```
$ go get -u github.com/swaggo/swag/cmd/swag
$ go get -u github.com/swaggo/gin-swagger 
$ go get -u github.com/swaggo/files
$ go get -u github.com/alecthomas/template

```
## 2.2 在项目根目录下查看 swag 安装情况
```
$ swag -v
swag version v1.8.7
```

#三、文档注释
## 3.1 在项目入口文件main 添加项目注释
```
// @title 项目名称(Exp: Brave-go-factory)
// @version 版本(Exp: v.1.0.1)
// @description (Exp: Brave-go-factory业务接口文档集合)

// @contact.name 联系人(Exp: BraveDu)
// @contact.email 邮箱(Exp: bravedu@gmail.com

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
func main() {

}
```
## 3.2 项目路由模块
```
import (
	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

var router = gin.New()

func InitRouter() *gin.Engine {
	router.Use(Cors())
	#设置swagger的路由前缀
	docs.SwaggerInfo.BasePath = ""
	// v1群组对任何人开放
	v1 := router.Group("/v1")
	{
		v1.POST("login", controller.Login)
	}
	// v2群组使用中间件JwtAuth，需要token权限才能请求到
	v2 := router.Group("/v2", authJwt.JwtAuthGinHandlerFunc())
	{
		v2.POST("hello-v2", controller.Login)
	}
	if gin.Mode() != gin.ReleaseMode {
		router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	}
	return router
}
```

## 3.3 如果针对swagger 生成的文档想指定访问
```
url := ginSwagger.URL("http://ip:8802/swagger/doc.json")

r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))
```

## 3.4 POST 接口注释,请求为json类型的
```
// Login
// @Summary 登录和注册接口
// @schemes https
// @Description
// @Tags
// @name BraveDu
// @Accept json
// @Produce json
// @Param Content-Type header string false "参数类型" default("application/json")
// @Param Authorization header string false "Bearer 用户令牌"
// @Param object body typespec.LoginReq true "手机号"
// @Security ApiKeyAuth
// @Success 200 {object} Result{data=typespec.LoginResp} "成功"
// @Failure 10004 {object} Result "失败, code状态码非0,显示error信息即可"
// @Router /v1/login [post]
func Login(c *gin.Context) {
```
## 3.5 GET 接口注释
```
// 接口名称
// @Summary 接口描述
// @schemes https
// @Description
// @Tags
// @Param activeId query int true "活动id"
// @Param page_size query int false "每页显示数量"
// @Param offset query int false "页码"
// @Accept json
// @Produce json
// @Success 200 {object} Result{data=typespec.HelloListResp} "成功"
// @Failure 10004 {object} Result
// @Router /v1/hello [get]
func Hello(c *gin.Context) {
```
###额外参数
```
//POST 时候body 标签
// @Param file formData file true "上传文件"
// @Param img_with formData string true "图片宽度尺寸"
```

#四、接口写完后生成文档
```
#项目个目录,命令行执行

swag init

#重启项目,访问

http://127.0.0.1:8802/swagger/index.html
```
![swag-doc.png](http://blogimg.bravedu.com/myblog/swag-doc.png)

#五、导入到APIfox
![apifox-1.png](http://blogimg.bravedu.com/myblog/apifox-1.png)

![swag-2.png](http://blogimg.bravedu.com/myblog/swag-2.png)
#五、参考资料

### go-swagger
https://github.com/swaggo/gin-swagger
### swag doc 帮助文档
https://github.com/swaggo/swag/blob/master/README_zh-CN.md

BraveDu

go+swagger项目接口文档生成整理

您可以选择一种方式赞助本站

发表评论