工作中后端是如何将API提供进来的？swaggo很不错

咱们上一次简略分享了 GO 权限治理之 Casbin ，他个别指依据零碎设置的平安规定或者安全策略

• 分享了权限治理是什么
• Casbin 是什么
• Casbin 的个性
• Casbin 的利用案例

要是感兴趣的话，咱们当前能够多多深刻的探讨和分享，欢送查看文章 GO 权限治理之 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的案例应用，大抵分为如下步骤：

• 装置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 mainimport (   "github.com/gin-gonic/gin"   ginSwagger "github.com/swaggo/gin-swagger"   "github.com/swaggo/gin-swagger/swaggerFiles"   "net/http"   _ "myswa/docs")// gin 的处理函数  Hellofunc 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 myswago 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 mainimport (    "github.com/gin-gonic/gin"    ginSwagger "github.com/swaggo/gin-swagger"    "github.com/swaggo/gin-swagger/swaggerFiles"    "net/http"    _ "myswa/docs")// gin 的处理函数  Hellofunc 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/v1func 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 ， 浏览器拜访http://127.0.0.1:8888/swagger/index.html咱们就能够看到如下成果

此时查看咱们生成的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/v1host: 127.0.0.1:8888info:  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显示的数据来源于上述 两个文件

对于上述正文中的关键字，咱们列一个表格瞅瞅

咱们给函数增加上对应的正文，看看成果

// @Summary hello world// @Description 对谁说 hello wrold// @Tags 挑战测试// @Accept json// @Param name query string true "具体名字"// @Success 200 {string} string "{"msg": "hello xxx"}"// @Failure 400 {string} string "{"msg": "NO name"}"// @Router /hello [get]// gin 的处理函数  Hellofunc Hello(c *gin.Context) {   name := c.Query("name")   c.JSON(http.StatusOK, gin.H{"msg": "hello wrold" + name})}

增加完正文后执行如下 3 步：

• 删除掉 之前生成的 docs 目录
• 再次在 main.go 同级目录下执行 swag init 生成最新的文档
• 执行 go run main.go ， 浏览器拜访http://127.0.0.1:8888/swagger/index.html咱们就能够看到如下成果

咱们在页面上做一下根本测试，填入name ，执行，看看成果

呐，测试胜利

如果将这样的文档给进来，对于前端来说就十分的敌对了，并且对于咱们的工作量没有什么减少，写代码的时候，顺便把正文写上去

公布

开发结束后，公布版本的时候，不可能还要带上本人的api文档吧，这是不应该的

因而，咱们能够通过 build tag 的形式来管制是否编译文档，这里留个悬念，感兴趣的敌人能够尝试一下

感兴趣的敌人，能够将上述代码贴到本地，装置对应的库，执行一下，看看成果，的确十分好用，心愿能帮忙到你

总结

• swaggo 是什么
• swagger 是什么
• 如何应用 swaggo
• 如何测试 swaggo

欢送点赞，关注，珍藏

敌人们，你的反对和激励，是我保持分享，提高质量的能源

好了，本次就到这里，下一次 GO 的定时器 timer 和定时工作cron

技术是凋谢的，咱们的心态，更应是凋谢的。拥抱变动，背阴而生，致力向前行。

我是小魔童哪吒，欢送点赞关注珍藏，下次见~