Golang 微服务框架 Kratos 轻松集成并使用 Swagger UI
Golang 微服务框架 Kratos 轻松集成并使用 Swagger UI
在我们的开发当中，调试接口，测试接口，提供接口文档给前端，那都是非常频繁的工作内容。
那么，我们需要用什么方法和工具来实施这些工作内容呢？
Swagger，或者说 OpenAPI。
下面先让我们了解一下下什么是 Swagger，什么是 OpenAPI。
什么是 OpenAPI
OpenAPI 是编写 RESTful API 的全球标准。它是一种规范，使得全球开发人员可以标准化 API 的设计，并在从头开始编写 REST API 时遵守所有安全、版本控制、错误处理和其他最佳实践。不仅仅是从头开始，即使现有的 API 也可以进行微调以符合全球标准。
此外，遵守开发产品的通用标准显然有助于什么。
最初，OpenAPI 被称为 Swagger 规范。Swagger 提出了构建 API 的最佳实践，然后这些最佳实践成为了 OpenAPI 规范。
像 SwaggerHub 这样的工具可以帮助开发人员在基于浏览器的编辑器中构建 API，符合标准并完全控制设计过程。
使用 Swagger Inspector 等工具，我们还可以生成自己的 API 规范，并将其传递给组织中的其他团队。
需进一步了解，可查看 OpenAPI 规范（中文版）。
什么是 Swagger
OpenAPI 是一个编写 API 文档的规范，然而如果手动去编写 OpenAPI 规范的文档，是非常麻烦的。而 Swagger 就是一个实现了 OpenAPI 规范的工具集。
Swagger 包含的工具集：
Swagger 编辑器： Swagger Editor 允许在浏览器中编辑 YAML 中的 OpenAPI 规范并实时预览文档。
Swagger UI： Swagger UI 是 HTML，Javascript 和 CSS 资产的集合，可以从符合 OAS 标准的 API 动态生成漂亮的文档。
Swagger Codegen：允许根据 OpenAPI 规范自动生成 API 客户端库（SDK 生成），服务器存根和文档。
Swagger Parser：用于解析来自 Java 的 OpenAPI 定义的独立库
Swagger Core：与 Java 相关的库，用于创建，使用和使用 OpenAPI 定义
Swagger Inspector（免费）： API 测试工具，可让您验证您的 API 并从现有 API 生成 OpenAPI 定义
SwaggerHub（免费和商业）： API 设计和文档，为使用 OpenAPI 的团队构建。
怎么样集成 Swagger 到 Kratos
首先，我们要了解的是：要在项目中集成 Swagger，唯一的办法就是通过 Swagger UI 来集成。
Swagger UI 依赖读取的是 OpenAPI 的 json 或者 yaml 格式的 API 文档，这个文档不是给人来读取的，而是给 Swagger UI。同样，它也不是给人来写的，靠的是生成器来生成的。
因此，下面首先我们需要来了解 API 是如何生成的，怎样生成的。
API 文档怎么产生呢？
因为 Kratos 是依托于 Protobuf 和 gRPC 来设计 API 的，所以，我们可以由相关的生成器工具来生成。
Protobuf 是一个 DSL 语言，它需要一个叫做 protoc 的工具来将 API 编译转换成目标语言。而它的具体工具是依靠插件来实现的。
目前已有的由 Go 编写的 OpenAPI 生成插件有两个：
OpenAPIv2 生成器：protoc-gen-openapiv2
OpenAPIv3 生成器：protoc-gen-openapi
我们可以通过以下命令来安装：
直接生成的命令倒是简单。
生成 OpenAPI v2 json 文档：
生成 OpenAPI v3 yaml 文档：
但是，直接使用命令是很不方便的，我们可以使用一个叫做Buf.Build来进行工程化生成。
安装 Buf 很简单：
然后我们需要在项目的根目录下创建buf.work.yaml、buf.yaml、buf.gen.yaml等配置文件。关于这些配置文件如何进行配置，本文将不做详细的讲解，可自行寻找教程学习。本文只着重讲解生成 OpenAPI 的相关知识。
要生成 OpenAPI，我们还需要创建一个配置文件buf.openapi.gen.yaml，并且放在 proto 同级目录下，在这里我们以后台 API 做讲解：
接着我们就可以在项目根目录下使用下面的命令来生成了：
最终，在./app/admin/service/cmd/server/assets这个目录下面，将会生成出来一个文件名为openapi.yaml的文件。
怎么将 openapi.yaml 文件引入到 Swagger UI
Kratos 官方本来是有一个swagger-api的项目的（现在已经被归档了），集成的是 OpenAPI v2 的 Swagger UI。这个项目呢，不好使，我在应用中，经常会读不出来 OpenAPI 的文档。还有就是 OpenAPI v2 不如 v3 功能强大。
因为没有支持，而我又需要跟前端进行沟通，所以我只好生成出 OpenAPI 文档之后，自行导入到 ApiFox 里面去使用，ApiFox 呢，挺好的，支持文件和在线两种方式导入，文档管理，接口测试的功能也都很强大。但是总是要去费神导出文档，这很让人抗拒——在开发的初期，接口变动是很高频的行为——难道就不能够全自动吗？程序只要一发布，接口就自动的跟随程序一起发布出去了。
对，说的就是集成 Swagger UI。
为了做到这件事，我需要做这么几件事情：
把 Buf 生成 OpenAPI 文档，编译运行程序写进 MakeFile 里面；
利用 golang 的
Embedding Files特性，把openapi.yaml嵌入到服务程序里面；集成 Swagger UI 到项目，并且读取内嵌的
openapi.yaml文档。
那么，我们首先开始编写 Makefile：
这样我们只需要运行make openapi就执行 OpenAPI 的生成了，调试运行的时候，输入make run命令就可以生成 OpenAPI 并运行程序。
Makefile 写好了，现在我们来到./app/admin/service/cmd/server/assets这个目录下面，我们在这个目录下面创建一个名为assets.go的代码文件：
就这样，我们就把 openapi.yaml 内嵌进程序了。
最后，我们就需要来集成 Swagger UI 进来了。我为此封装了一个项目，要使用它，我们需要：
在创建 REST 服务器的地方调用程序包里面的方法：
自此我们就大功告成了！
如果 API 服务的端口是 8080，那么我们可以访问链接来访问 Swagger UI：
同时，openapi.yaml 文件也可以在线访问到：
http://localhost:8080/docs/openapi.yaml
结语
作为程序员，偷懒是一个美德，因为要想偷懒，就必须要想尽办法改善流程，制造工具，能自动化的就自动化。而集成 Swagger UI 在工作中也确实切实的减轻了我和团队的工作量，提升了开发效率。
如果你对 Kratos 集成 Swagger UI 还有什么不太明白的，我有一个开源的 CMS 项目，里面有完整的应用代码：
参考资料
版权声明: 本文为 InfoQ 作者【喵个咪】的原创文章。
原文链接:【http://xie.infoq.cn/article/0cc0f236054e1562b709b5418】。
本文遵守【CC-BY 4.0】协议，转载请保留原文出处及本版权声明。
还未添加个人签名 2022-06-01 加入
还未添加个人简介
评论