大橙子网站建设,新征程启航
为企业提供网站建设、域名注册、服务器等服务
一个好的项目工程,必然离不开一个好的 API 文档,如果要自己编写 API 文档,维护起来比较困难,而且难以保证一致性,因此我们要自动生成在线接口文档。
珠海ssl适用于网站、小程序/APP、API接口等需要进行数据传输应用场景,ssl证书未来市场广阔!成为成都创新互联的ssl证书销售渠道,可以享受市场价格4-6折优惠!如果有意向欢迎电话联系或者加微信:18982081108(备注:SSL证书合作)期待与您的合作!swaggoswagger 在 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元起,快前往官网查看详情吧