前言

一个好的项目工程，必然离不开一个好的 API 文档，如果要自己编写 API 文档，维护起来比较困难，而且难以保证一致性，因此我们要自动生成在线接口文档。

珠海ssl适用于网站、小程序/APP、API接口等需要进行数据传输应用场景，ssl证书未来市场广阔！成为成都创新互联的ssl证书销售渠道，可以享受市场价格4-6折优惠！如果有意向欢迎电话联系或者加微信：18982081108（备注：SSL证书合作）期待与您的合作！swaggo

swagger 在 java 里面，是一个非常流行的 api 组件，他们维护了 go 版本 swaggo，
可以通过 Swagger 2.0 自动生成RESTful API 文档。
swaggo 项目链接

安装 下载代码

# 最新版本
go get -u github.com/swaggo/swag/cmd/swag

# 可以加上版本号
go get -u github.com/swaggo/swag/cmd/swag@v1.8.8

另外还需要下载两个包

# gin-swagger 中间件
go get github.com/swaggo/gin-swagger

# swagger 内置文件
go get github.com/swaggo/gin-swagger/swaggerFiles

安装到 $PATH

若$GOPATH的bin目录下面没有swag文件，需要go install

cd $GOPATH/pkg/mod/github.com/swaggo/swag@v1.8.8/cmd/swag
# 安装
go install

若$GOROOT/bin没有加入$PATH中，需要将其可执行文件移动到$GOBIN下

mv $GOPATH/bin/swag /usr/local/go/bin

检查安装

出现这个情况，说明安装成功了

$ swag -v
swag version v1.8.8

gin 集成 swaggo 编写 api 注释

Swagger 中需要将相应的注释或注解编写到方法上，再利用生成器自动生成说明文件

gin-swagger 给出的范例：

// @Summary Add a new pet to the store
// @Description get string by ID
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string	"ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]

参照Swagger的注解规范和范例去编写

// Register
// @Tags 用户管理
// @Summary 用户注册
// @Param username formData string true "username"
// @Param password formData string true "password"
// @Success 200 {string} json "{"code":"200","msg":"success","data":""}"
// @Router /register [post]
func Register(c *gin.Context) {}

路由

在完成了api注释的编写后，我们需要针对 swagger 新增初始化动作和对应的路由规则，才可以使用。在routers/router.go文件，增加swagger的路由：

func Router() *gin.Engine {r := gin.Default()
	
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))

	return r
}

生成

在项目目录下，执行swag init

2022/12/04 15:27:52 Generate swagger docs....
2022/12/04 15:27:52 Generate general API Info, search dir:./
2022/12/04 15:27:52 create docs.go at  docs/docs.go
2022/12/04 15:27:52 create swagger.json at  docs/swagger.json
2022/12/04 15:27:52 create swagger.yaml at  docs/swagger.yaml

执行完成后会在项目根目录下生成docs目录，里面就是api文档相关的内容

docs/
├── docs.go
└── swagger
    ├── swagger.json
    └── swagger.yaml

可以看一下json的内容，其他的也是一样的，只是格式不同

查看文档

访问地址

http://127.0.0.1:8080/swagger/index.html

其他信息

在main.go方法上，可以增加一些其他信息，完善项目的信息

// @title Swagger Example API
// @version 1.0
// @description This is a sample server celler server.
// @termsOfService https://github.com/stream108

// @contact.name 一江溪水
// @contact.url https://github.com/stream1080
// @contact.email https://github.com/stream108

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 127.0.0.1:8080
// @BasePath /api/v1

你是否还在寻找稳定的海外服务器提供商？创新互联www.cdcxhl.cn海外机房具备T级流量清洗系统配攻击溯源，准确流量调度确保服务器高可用性，企业级服务器适合批量采购，新人活动首月15元起，快前往官网查看详情吧

本文题目：gin集成Swagger-创新互联
网站链接：http://chengdu.cdxwcx.cn/article/ddoces.html