使用 OpenAPI 到底有什么意义？ [关闭]

Question

尽管我在日常工作中一遍又一遍地构建和使用 REST API，但我并不是来自使用 OpenAPI 或类似工具的背景。在我目前的角色中，我们总是定义 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 生态系统中存在很多工具 (see this list)。它不仅仅是代码生成器。

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

TL;DR

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

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

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

如果使用得当，它可以让你的生活轻松很多。

Answer 2

好吧，我可以在这里列出一些您可以获得的优势

1. 您的 API 已记录在案。
2. 任何外部客户端都可以轻松地阅读您为 REST API 指定的合同以及它们如何与您的 API 集成，而无需与您的开发团队交谈并安排与您的技术主管的会议。
3. 通常，资源可以有多个表示，主要是因为可能有多个不同的客户端期望不同的表示。如果您使用可视化工具生成您的 基于您的 OpenAPI 格式的文档，您可以轻松地展示 同一个资源，你使用的所有模型都基于内容 协商（例如 Content-Types/Accept 标头）
4. 如果您有有效的 OpenAPI（Swagger 格式），您可以导入文档并将其托管在 API 网关上，它可以作为您所有外部客户端的入口点来搜索他们需要与您的集成的 API组织。此外，您还可以 生成一些 API 密钥并确定哪个客户端正在使用您的 API。
   5. 如果您为文档生成 UI，则无需使用邮递员进行一些测试并将数据获取/发布到您的 API。
   6. Visual Studio 现在有一项功能，您可以在其中传递 API 的 URL，它会为您发现端点并创建一个 HttpClient 以开始使用它。

希望对你有帮助