使用 OpenAPI 的意义何在？

Question

我没有使用 OpenAPI 或类似的背景，即使我在日常工作中一遍又一遍地构建和使用 REST API。在我目前的角色中，我们总是定义 OpenAPI 规范，这似乎是流程的假定部分。团队将其视为非常重要的。

但是，我终其一生都无法认识到它的任何好处。我试图更好地理解。

在我知道它可以做的事情中，没有一个似乎是有益的，恕我直言，但我必须错过一些东西。

• OpenAPI 规范可以生成文档，但在我看来，文档是供人类阅读的，应该由人类编写。生成的文档可能包含所有内容，但不包含使用整个 API 的上下文和细微差别。
• OpenAPI 规范可以为单个 API 生成多种语言的客户端代码。通常，这些只是将 REST URL 结构映射到方法名称。这真的有用吗？这意味着我可能会做client.books.get(title="Moby Dick")而不是client.get("/books", {'title': 'Moby Dick'}). 它所做的一切都是围绕相同的名称进行转换，而不是使任何事情变得更容易或更简洁。那么，再一次，有什么意义呢？生成的客户端似乎根本没有添加任何内容。

任何人都可以启发我吗？

Answer 1

OpenAPI 规范本身并不是一件有益的事情。根据我的经验，它们在许多服务相互交互的微服务环境中是一个巨大的好处。

与所有接口一样，RESTful 接口可以被视为服务提供者和服务消费者之间的契约。

提供者承诺提供一组特定的操作，消费者可以订阅这些操作及其各自的端点。

在这种情况下，OpenAPI 规范是参与者可以达成一致的合同法案。如果他们一开始不同意，他们可以协商 api 规范。

当然，这是一个非技术方面。

在更多的技术方面，我觉得三个方面非常有用

1. 从单一来源生成代码和文档

在文档方面有几个丑陋的事实：没有人喜欢写它，没有人喜欢阅读它，而且大多数时候，它已经过时了。

使用 OpenAPI 规范和其他类似工具，您拥有用于生成实际代码和文档的规范。它们都不会过时的可能性要高一点。然而，机会仍然不是100%。

2. 无需编写样板代码

使用 OpenAPI 规范，不再需要手动实现数据类以及简单的客户端和服务器代码。对于很多用例，您可以省略设置项目——您不需要编写 spring-boot-server 或 java 数据传输对象。如果你有 api 规范，生成器会为你做这件事。

当您处理仅提供少量端点和数据对象的简单 api 时，这并不是什么大事。但是，一旦您面对数百个端点和数据类（就像我所拥有的那样），手头编写好的 api 规范会使事情变得容易得多。

3. 工装

开放 api 生态系统中存在许多工具（请参阅此列表）。它不仅仅是代码生成器。

有一个很棒的浏览器内的规范文件编辑器，有数据验证器、测试数据生成器等。

TL; 博士

你当然是对的。基本上 OpenAPI 及其背后的整个工具套件将生成客户端和服务器代码，并充当其余端点和生成的代码之间的映射器。

但是编写映射代码可能很乏味且容易出错。最好让一些工具为你做这件事。

此外，机器可读的 api 规范可以作为 api 合同账单。它可以在 git 存储库上进行版本控制并通过 nexus 存储库分发。

如果使用得当，它可以让您的生活更轻松。