工作中后端是如何将API提供出去的?swaggo很不错
工作中后端是如何将API提供出去的?swaggo很不错
咱们上一次简单分享了 GO 权限管理之 Casbin ,他一般指根据系统设置的安全规则或者安全策略
- 分享了权限管理是什么
- Casbin 是什么
- Casbin 的特性
- Casbin 的应用案例
要是感兴趣的话,咱们以后可以多多深入的探讨和分享,欢迎查看文章
今天咱们来分享一下咱们在工作中,后端的小伙伴是如何将 API
高效的提供出去的呢?
API 由一组定义和协议组合而成,可用于构建和企业集成应用软件 API 就是 应用编程接口
相信有很多朋友喜欢写文档的,可能会使用markdown
将接口写下来,相关负责人约定好一个固定的模板
有的会使用简单的文本文件,有的大兄弟可能连一点文档资料都不输出,这样在电视剧里面是活不过第二集的
那么测试的时候呢?
一般会使用postman
工具,对照着接口进行参数的设置,进行自测,或者写脚本进行测试
可是,这样都太麻烦了,还要花太多的时间在书写接口上面,每次修改接口还要对应的修改文档,相当繁琐,有点反人性
那咱们来看看 GO swaggo
工具 是如何解决上述问题的,都有哪些骚操作吧
swaggo 是什么?
是一个工具,专门用于将 golang
注解自动转换为Swagger 2.0
文档
Swagger 又是个啥?
Swagger
是一个Web 服务 他是一个规范且完整的框架,可以生成、描述、调用和可视化 RESTful 风格的文档
那么他的优势是个啥?
大致有如下 2 个优势:
- 支持 API 自动生成同步的在线文档
使用 Swagger
后可以直接通过代码生成文档,不再需要自己手动编写接口文档了
- 提供了 Web 页面在线测试 API
Swagger
生成的文档还支持在线测试
参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口,用起来真的别提多香了
swaggo 都有哪些功能呢?
咱们如何使用 swaggo?
咱们来写一个最基本你的swaggo
的案例使用,大致分为如下步骤:
- 安装
swag
,用于自动生成文档
go get -u github.com/swaggo/swag/cmd/swag
- 需要使用到如下 2 个包, 可以先知悉一下,咱们还是默认是用go mod 的方式,写完代码之后 直接go build ,会将用到的包都拉下来
第一个是 gin-swagger
, 咱们用gin 来玩 swagger 比较方便,之前也和大家分享过gin
的使用,感兴趣的可以查看文章 Gin实战演练
go get github.com/swaggo/gin-swagger
第二个是swagger
内置文件
go get github.com/swaggo/gin-swagger/swaggerFiles
- 需要简单使用 gin 框架
咱们开始编码一个简单的小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 步:
- 删除掉 之前生成的 docs 目录
- 再次在
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显示的数据来源于上述 两个文件
对于上述注释中的关键字,咱们列一个表格瞅瞅
总结
- 分享了权限管理是什么
- Casbin 是什么
- Casbin 的特性
- Casbin 的应用案例
欢迎点赞,关注,收藏
朋友们,你的支持和鼓励,是我坚持分享,提高质量的动力
好了,本次就到这里,下一次 GO 的定时器 timer 和定时任务cron
技术是开放的,我们的心态,更应是开放的。拥抱变化,向阳而生,努力向前行。
我是小魔童哪吒,欢迎点赞关注收藏,下次见~