早在 2018 年,我就被分配为我的团队构建新工具。这是我有机会独立工作的大项目之一。因为这对我来说是第一个大项目,所以我脑子里几乎没有什么东西。

• 独立构建客户端-服务器(不是作为单回购)

• 使用有良好社区支持的技术

• API首次开发

面临的挑战

因此,在开始任何功能之前,我们所有人(3 人的小团队)都将讨论 API,我们将公开 API 将使用和产生的所有参数,并将正确记录它的内部文字文档。那时我们是 REST API 开发的新手,我们不知道如何正确记录 API;因此,我们遇到了一些问题:

• 当其中一位开发人员需要进行任何更改时,他们会在我们的聊天频道中通知我们并更新更改。了解有时我们依赖它们的变化。

• 项目进入 6 个月后,另一位新开发人员加入了我们的团队,因为任务艰巨。设置服务器更容易,因为我们有一些脚本文件,但要模拟现有的 API 有点困难。

• 我们没有极好的阅读体验。给定参数的原因是什么,是否强制,数据类型是什么,可接受的值是什么

我们得到的解决方案

有句名言

患难见真情

在我的情况下这是真的。我正在和我的一位朋友讨论,他有探索很多东西的习惯,他建议检查Swagger。在我之前的一篇文章中,我提到了 OpenAPI 规范。 swagger 这个名字一直使用到 V2;从 V3 开始,我们开始使用 OpenAPI 倡议,一旦它进入 linux 基础。

OpenAPI 规范使机器和用户都可以轻松读取 JSON 文件并理解它们。当使用 OpenAPI Spec 编写 API 文档时,我们可以使用它来生成客户端库、网站或进行测试。

这完全为我们改变了商店。从那时起,我们改变了我们的 API 文档工作流程。

• 我们将使用 OpenAPI Spec (JSON 格式) 编写 API 文档

• 我们可以在我们的机器本地写在VSCode本身

• 我们会将它推送到我们的中央 git repo

更好的 OpenAPI 规范编写工具

• VS代码

• Swagger 查看器

• 基于 Git 的 repo(很多基于 git 的工作流即将出现,所以最好坚持这个)

理解差异

自从我们开始使用 git 版本控制(以前只是一个普通文档;现在它的可读性更高的 JSON 文件)我们能够看到 git 提交和两个提交之间的差异。

更容易的开发人员入职

对于 API 开发,我们使用Postman,这是很棒的工具。如前所述,一旦服务器设置完成,而不是手动复制和粘贴每个 API URL 和数据,现在我们导入 API JSON 文件(基于 Open API 规范)。

快捷键:Ctrl + O

更易阅读

在 VSCode 中,我们安装了Swagger 查看器扩展,它可以帮助我们轻松阅读文档。

我们还可以创建静态网站并发布到网站。

要开始使用 OpenAPI,请查看详细的文档

更轻松的自动化测试

其中一位开发人员编写了一个小程序,我们将在其中阅读规范文档并验证响应和响应代码。

如果您想在线玩 Open API 规范,可以查看swagger editor

为什么 OpenAPI 规范很受欢迎

• 易于编写的 REST API 文档。我们可以用 JSON 格式或 YAML 格式编写。

• 更好的编辑、查看工具。

• 社区支持

OpenAPI 规范帮助我们简化了 REST API 文档的编写,我们使用客户端-服务器或某些服务器-服务器进行通信。当我们要使用异步通信模式时,我们可以检查AsyncAPI