工作中后端是如何将 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 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，浏览器拜访 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/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 显示的数据来源于上述 两个文件

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

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

// @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 的处理函数  Hello
func 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

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

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