Go语言微服务框架 - 10.接口文档-openapiv2的在线文档方案

简介: 随着项目的迭代,一个服务会开放出越来越多的接口供第三方调用。虽然`protobuf`已经是通用性很广的IDL文件了,但对于未接触过这块的程序员来说,还是有很大的学习成本。在综合可读性和维护性之后,我个人比较倾向于使用oepnapiv2的方案,提供在线接口文档。

随着项目的迭代,一个服务会开放出越来越多的接口供第三方调用。

虽然protobuf已经是通用性很广的IDL文件了,但对于未接触过这块的程序员来说,还是有很大的学习成本。在综合可读性和维护性之后,我个人比较倾向于使用oepnapiv2的方案,提供在线接口文档。

接下来,我们一起来看看这部分的实现。

v0.7.0:接口文档-openapiv2的在线文档方案

项目链接 https://github.com/Junedayday/micro_web_service/tree/v0.7.0

目标

项目提供在线接口文档,供第三方快速地了解接口细节。

关键技术点

  1. 了解buf的openapiv2的插件
  2. 用swagger工具合并文档
  3. 利用swagger相关容器提供在线文档

swagger 是 openapiv2 的一种具体实现,在下文可等同于一个概念。

可以参考swagger官网了解详情:https://swagger.io/specification/v2/

目录构造

--- micro_web_service            项目目录
    |-- gen                            从idl文件夹中生成的文件,不可手动修改
       |-- idl                             对应idl文件夹
          |-- demo                             对应idl/demo服务,包括基础结构、HTTP接口、gRPC接口
            |-- order                            对应idl/order服务,同上
     |-- swagger.json                    新增:openapiv2的接口文档
    |-- idl                            原始的idl定义
       |-- demo                            业务package定义,protobuffer的原始定义
       |-- order                           业务order定义,同时干
    |-- internal                       项目的内部代码,不对外暴露
       |-- config                          配置相关的文件夹,viper的相关加载逻辑
       |-- dao                             Data Access Object层,是model层的实现
       |-- gormer                          从pkg/gormer中生成的相关代码,不允许更改
       |-- model                           model层,定义对象的接口方法,具体实现在dao层
       |-- mysql                           MySQL连接
       |-- server                          服务器的实现,对idl中定义服务的具体实现
       |-- service                         service层,作为领域实现的核心部分
     |-- zlog                            封装zap日志的代码实现
  |-- pkg                            开放给第三方的工具库
     |-- gormer                          gormer二进制工具,用于生成Gorm相关Dao层代码
    |-- buf.gen.yaml                   buf生成代码的定义,从v1beta升到v1
    |-- buf.yaml                       buf工具安装所需的工具,从v1beta升到v1
    |-- gen.sh                         生成代码的脚本:buf+gormer
    |-- go.mod                         Go Module文件
    |-- gormer.yaml                    将gormer中的参数移动到这里
    |-- main.go                        项目启动的main函数
    |-- swagger.sh                     新增:生成openapiv2的相关脚本

1.了解buf的openapiv2的插件

gRPC-Gateway的文档中,我们可以找到对应的buf插件使用方式:在buf.gen.yaml文件中,我们添加如下插件内容:

version: v1
plugins:
  - name: openapiv2
    out: gen/openapiv2

运行buf generate后,在gen/openapiv2目录下会根据我们在idl文件中的目录结构,生成多个接口文档。

2.用swagger工具合并文档

用buf标准的openapiv2插件会生成多份swagger文档,管理多个文件对使用方来说并不方便。最佳的使用体验,就是能将多个文档合并起来,用一个API文档统一交付。

这里,我们借助goswagger工具,合并文档。工具具体的安装方式可参考链接:https://goswagger.io/install.html。

安装后,运行如下命令,生成到文件 gen/swagger.json:

# 合并swagger文档
swagger mixin gen/openapiv2/idl/*/*.json -o gen/swagger.json
# 删除原始文档
rm -rf gen/openapiv2

3.利用swagger相关容器提供在线文档

在统一了swagger文件后,在线接口文档的实现方案有很多,例如swagger官网就可以提供简单的渲染。

这里,我用了个人比较常用的docker镜像redoc为例,搭建一个在线接口文档平台。

该镜像更多的使用方式可参考:https://hub.docker.com/r/redocly/redoc/

运行如下命令,即将swagger.json加载到镜像中:

docker run --name swagger -it --rm -d -p 80:80 -v $(pwd)/gen/swagger.json:/usr/share/nginx/html/swagger.json -e SPEC_URL=swagger.json redocly/redoc

我们在本地打开浏览器,输入 http://127.0.0.1:80/ 就能看到文档。

扩展点 - 公共的文档服务器:

我们往往更希望把文档放在一个公共的服务器上,可以简单地利用这两个关键技术实现:

  1. https://hub.docker.com/r/redocly/redoc/ 中的watch方案,即watch某个目录下的文件,根据文件变化实时更新接口
  2. 利用scp命令,将本地swagger.json上传到远端服务器

更复杂点的方案,可以考虑结合git流程来实现。

总结

至此,我们实现了一个关键性的功能:代码即接口文档,保证了接口文档随着代码更新的实时性。

同时,希望大家能够认识到接口文档的价值,最好能做到接口文档即代码,也就是将相关程序的逻辑尽可能地通过接口文档表达清楚。哪怕前期接口文档问题很多,只要我们不断迭代,后续总能趋于稳定,降低维护接口的成本。

目录
相关文章
|
8天前
|
存储 监控 算法
员工上网行为监控中的Go语言算法:布隆过滤器的应用
在信息化高速发展的时代,企业上网行为监管至关重要。布隆过滤器作为一种高效、节省空间的概率性数据结构,适用于大规模URL查询与匹配,是实现精准上网行为管理的理想选择。本文探讨了布隆过滤器的原理及其优缺点,并展示了如何使用Go语言实现该算法,以提升企业网络管理效率和安全性。尽管存在误报等局限性,但合理配置下,布隆过滤器为企业提供了经济有效的解决方案。
44 8
员工上网行为监控中的Go语言算法:布隆过滤器的应用
|
28天前
|
Go 开发工具
百炼-千问模型通过openai接口构建assistant 等 go语言
由于阿里百炼平台通义千问大模型没有完善的go语言兼容openapi示例,并且官方答复assistant是不兼容openapi sdk的。 实际使用中发现是能够支持的,所以自己写了一个demo test示例,给大家做一个参考。
|
28天前
|
程序员 Go
go语言中结构体(Struct)
go语言中结构体(Struct)
100 71
|
27天前
|
存储 Go 索引
go语言中的数组(Array)
go语言中的数组(Array)
104 67
|
3天前
|
算法 安全 Go
Go 语言中实现 RSA 加解密、签名验证算法
随着互联网的发展,安全需求日益增长。非对称加密算法RSA成为密码学中的重要代表。本文介绍如何使用Go语言和[forgoer/openssl](https://github.com/forgoer/openssl)库简化RSA加解密操作,包括秘钥生成、加解密及签名验证。该库还支持AES、DES等常用算法,安装简便,代码示例清晰易懂。
28 16
|
6天前
|
监控 算法 安全
解锁企业计算机监控的关键:基于 Go 语言的精准洞察算法
企业计算机监控在数字化浪潮下至关重要,旨在保障信息资产安全与高效运营。利用Go语言的并发编程和系统交互能力,通过进程监控、网络行为分析及应用程序使用记录等手段,实时掌握计算机运行状态。具体实现包括获取进程信息、解析网络数据包、记录应用使用时长等,确保企业信息安全合规,提升工作效率。本文转载自:[VIPShare](https://www.vipshare.com)。
19 0
|
20天前
|
Go 数据安全/隐私保护 UED
优化Go语言中的网络连接:设置代理超时参数
优化Go语言中的网络连接:设置代理超时参数
|
28天前
|
存储 Go 索引
go语言中数组和切片
go语言中数组和切片
38 7
|
30天前
|
Go 索引
go语言for遍历数组或切片
go语言for遍历数组或切片
98 62