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

工作中后端是如何将API提供出去的？swaggo很不错.jpg

咱们上一次简单分享了 GO 权限管理之 Casbin ，他一般指根据系统设置的安全规则或者安全策略

• 分享了权限管理是什么
• Casbin 是什么
• Casbin 的特性
• Casbin 的应用案例

要是感兴趣的话，咱们以后可以多多深入的探讨和分享，欢迎查看文章 GO 权限管理之 Casbin

今天咱们来分享一下咱们在工作中，后端的小伙伴是如何将 API 高效的提供出去的呢？

API 由一组定义和协议组合而成，可用于构建和企业集成应用软件

API 就是 应用编程接口

image

相信有很多朋友喜欢写文档的，可能会使用markdown将接口写下来，相关负责人约定好一个固定的模板

有的会使用简单的文本文件，有的大兄弟可能连一点文档资料都不输出，这样在电视剧里面是活不过第二集的 image

那么测试的时候呢？

一般会使用postman工具，对照着接口进行参数的设置，进行自测，或者写脚本进行测试

可是，这样都太麻烦了，还要画太多的时间在书写接口上面，每次修改接口还要对应的修改文档，相当繁琐，有点反人性

那咱们来看看 GO swaggo工具 是如何解决上述问题的，都有哪些骚操作吧

swaggo 是什么？

是一个工具，专门用于将 golang 注解自动转换为Swagger 2.0文档

Swagger 又是个啥？

Swagger 是一个Web 服务

他是一个规范且完整的框架，可以生成、描述、调用和可视化 RESTful 风格的文档

那么他的优势是个啥？

大致有如下 2 个优势：

• 支持 API 自动生成同步的在线文档

使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了

• 提供了 Web 页面在线测试 API

Swagger 生成的文档还支持在线测试

参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口，用起来真的别提多香了

image

咱们如何使用 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

image

此处可以检查一下，是否安装swag 成功

go get -u github.com/swaggo/swag/cmd/swag

安装成功后，可以使用 swag init 进行初始化，swag 会帮我们生成相应的docs，例如我的代码目录是这个样子的

这也就是为什么咱们导入的包中有一个是 _ "myswa/docs"

image

再次在浏览器中键入：

http://127.0.0.1:8888/swagger/index.html，可以查看到如下效果，则为成功

image image

添加注释

咱们在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咱们就可以看到如下效果

image

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

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

tag	说明
titile	文档标题
version	版本
description	描述，可写可不写
host	服务文档的端口
BasePath	基础路径
Summary	总结
Description	描述
Tags	用来给API分组
Accept	接收的参数类型，支持表单(mpfd) 和 JSON(json)
Param	参数，具体的写法如下：<br />@Param 参数名 参数类型 参数数据类型 是否必须 参数描述 其他属性<br />参数的类型<br />- path 这个类型的值可以直接拼接到 URL上面<br />@Param name path string true "具体名字"- query 这个类型值 一般是 和 URL 进行组合<br /><br />- query 这个类型值 一般是 和 URL 进行组合<br />@Param name query string true "具体名字"<br /><br />- formData 这个类型的值 一般是用于 POST 方法，或者 PUT方法 <br />@Param name formData string true "具体名字" default(root)<br /><br />参数的数据类型有如下几种<br />string(string) , integer (int, uint, uint32, uint64) , number (float32) , boolean (bool) , file 用于上传文件<br /><br />其他属性支持**：<br />- 枚举<br />- 值的添加范围<br />- 设置默认值<br />
Success	响应成功的情况如何处理 <br />@Success HTTP响应码 {响应参数类型} 响应数据类型 其他描述
Failure	响应失败的情况如何处理<br />@FailureHTTP响应码 {响应参数类型} 响应数据类型 其他描述
Router	路由 ， 不加基础路径的<br /> @Router /hello [get]

image

我们给函数添加上对应的注释，看看效果

// @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咱们就可以看到如下效果

image

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

image

呐，测试成功

如果将这样的文档给出去，对于前端来说就非常的友好了，并且对于我们的工作量没有什么增加，写代码的时候，顺便把注释写上去

image

发布

开发完毕后，发布版本的时候，不可能还要带上自己的api文档吧，这是不应该的

因此，咱们可以通过 build tag 的方式来控制是否编译文档，这里留个悬念，感兴趣的朋友可以尝试一下

感兴趣的朋友，可以将上述代码贴到本地，安装对应的库，执行一下，看看效果，确实非常好用，希望能帮助到你

总结

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

欢迎点赞，关注，收藏

朋友们，你的支持和鼓励，是我坚持分享，提高质量的动力

image

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

技术是开放的，我们的心态，更应是开放的。拥抱变化，向阳而生，努力向前行。

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