工作中后端是如何将API提供出去的?swaggo很不错
咱们上一次简单分享了 GO 权限管理之 Casbin ,他一般指根据系统设置的安全规则或者安全策略
要是感兴趣的话,咱们以后可以多多深入的探讨和分享,欢迎查看文章
今天咱们来分享一下咱们在工作中,后端的小伙伴是如何将 API
高效的提供出去的呢?
API 由一组定义和协议组合而成,可用于构建和企业集成应用软件 API 就是 应用编程接口
相信有很多朋友喜欢写文档的,可能会使用markdown
将接口写下来,相关负责人约定好一个固定的模板
有的会使用简单的文本文件,有的大兄弟可能连一点文档资料都不输出,这样在电视剧里面是活不过第二集的
那么测试的时候呢?
一般会使用postman
工具,对照着接口进行参数的设置,进行自测,或者写脚本进行测试
可是,这样都太麻烦了,还要花太多的时间在书写接口上面,每次修改接口还要对应的修改文档,相当繁琐,有点反人性
那咱们来看看 GO swaggo
工具 是如何解决上述问题的,都有哪些骚操作吧
是一个工具,专门用于将 golang
注解自动转换为Swagger 2.0
文档
Swagger
是一个Web 服务 他是一个规范且完整的框架,可以生成、描述、调用和可视化 RESTful 风格的文档
那么他的优势是个啥?
大致有如下 2 个优势:
使用 Swagger
后可以直接通过代码生成文档,不再需要自己手动编写接口文档了
Swagger
生成的文档还支持在线测试
参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口,用起来真的别提多香了
咱们来写一个最基本你的swaggo
的案例使用,大致分为如下步骤:
swag
,用于自动生成文档 go get -u github.com/swaggo/swag/cmd/swag
第一个是 gin-swagger
, 咱们用gin 来玩 swagger 比较方便,之前也和大家分享过gin
的使用,感兴趣的可以查看文章 Gin实战演练
go get github.com/swaggo/gin-swagger
第二个是swagger
内置文件
go get github.com/swaggo/gin-swagger/swaggerFiles
咱们开始编码一个简单的小DEMO
package main
import (
"github.com/gin-gonic/gin"
ginSwagger "github.com/swaggo/gin-swagger"
"github.com/swaggo/gin-swagger/swaggerFiles"
"net/http"
_ "myswa/docs"
)
// gin 的处理函数 Hello
func Hello(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"msg": "hello wrold xiaomotong" })
}
func main() {
r := gin.Default()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
// 路由分组, 第一个版本的api v1
v1 := r.Group("/api/v1")
{
v1.GET("/hello", Hello)
}
// 监听端口为 8888
r.Run(":8888")
}
上述代码大致分为这几步:
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
将 swaggerFiles.Handler 注册上上述代码编写完毕之后,咱们可以在和main.go
的同级目录中初始化一个 go
的模块,再go build
咱们运行程序
go mod init myswa
go build
上述命令 go mod init myswa
,初始化模块为 myswa ,以后导入咱们的本地包路径都需要是以myswa开头
执行上述命令后,会初始化一个myswa
的模块,执行go build
后,会将用到的相关包拉下来,进行编译
编译成功后在浏览器中键入:
http://127.0.0.1:8888/swagger/index.html
若查看到如下错误打印消息,原因是没有安装swag
的docs
此处可以检查一下,是否安装swag 成功
go get -u github.com/swaggo/swag/cmd/swag
安装成功后,可以使用 swag init 进行初始化,swag
会帮我们生成相应的docs
,例如我的代码目录是这个样子的
这也就是为什么咱们导入的包中有一个是 _ "myswa/docs"
再次在浏览器中键入:
http://127.0.0.1:8888/swagger/index.html
,可以查看到如下效果,则为成功
咱们在main.go
文件中,加入点注释,再看看效果,例如
package main
import (
"github.com/gin-gonic/gin"
ginSwagger "github.com/swaggo/gin-swagger"
"github.com/swaggo/gin-swagger/swaggerFiles"
"net/http"
_ "myswa/docs"
)
// gin 的处理函数 Hello
func Hello(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"msg": "hello wrold xiaomotong" })
}
// @title Xiaomotong Swagger API
// @version 1.0
// @description 参加更文挑战第 26 天了,主题是 Swagger
// @termsOfService https://juejin.cn/user/3465271329953806
// @contact.name https://juejin.cn/user/3465271329953806
// @contact.url https://juejin.cn/user/3465271329953806
// @contact.email xxx@xxx.com.cn
// @host 127.0.0.1:8888
// @BasePath /api/v1
func main() {
r := gin.Default()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
// 路由分组, 第一个版本的api v1
v1 := r.Group("/api/v1")
{
v1.GET("/hello", Hello)
}
// 监听端口为 8888
r.Run(":8888")
}
添加完注释后执行如下 3 步:
main.go
同级目录下执行 swag init
生成最新的文档go run main.go
, 咱们就可以看到如下效果此时查看咱们生成的docs目录下看看具体文件内容都有个啥?
这些都是自动生成的
my_swa/docs/swagger.json 如下
{
"swagger": "2.0",
"info": {
"description": "参加更文挑战第 26 天了,主题是 Swagger",
"title": "Xiaomotong Swagger API",
"termsOfService": "https://juejin.cn/user/3465271329953806",
"contact": {
"name": "https://juejin.cn/user/3465271329953806",
"url": "https://juejin.cn/user/3465271329953806",
"email": "xxx@xxx.com.cn"
},
"version": "1.0"
},
"host": "127.0.0.1:8888",
"basePath": "/api/v1",
"paths": {}
}
my_swa/docs/swagger.yaml如下:
basePath: /api/v1
host: 127.0.0.1:8888
info:
contact:
email: xxx@xxx.com.cn
name: https://juejin.cn/user/3465271329953806
url: https://juejin.cn/user/3465271329953806
description: 参加更文挑战第 26 天了,主题是 Swagger
termsOfService: https://juejin.cn/user/3465271329953806
title: Xiaomotong Swagger API
version: "1.0"
paths: {}
swagger: "2.0"
实际UI显示的数据来源于上述 两个文件
对于上述注释中的关键字,咱们列一个表格瞅瞅
朋友们,你的支持和鼓励,是我坚持分享,提高质量的动力
好了,本次就到这里,下一次 GO 的定时器 timer 和定时任务cron
技术是开放的,我们的心态,更应是开放的。拥抱变化,向阳而生,努力向前行。
我是小魔童哪吒,欢迎点赞关注收藏,下次见~