使用Spring Boot和OpenAPI 3.0进行API优先开发 | Baeldung

1. 引言

软件工程行业越来越依赖于Web API。云计算和HTTP的日益使用可能解释了这一点。

软件开发团队必须确保他们设计的API既有帮助又易于用户使用。传统开发方法中的主要挑战是在同时设计API契约和实现新产品的业务逻辑时保持敏捷性。

在本文中，我们将介绍使用Spring Boot和OpenAPI 3.0的API优先开发。这种方法通过及时的API设计反馈、快速失败流程和并行工作，提高了团队的沟通和敏捷性。

2. 什么是OpenAPI规范

OpenAPI规范（OAS）标准化了如何创建API设计文档。使用OAS的API优先方法的典型工作流程如下：

• 团队创建设计文档并将其分享给相关人员以获取反馈和迭代更改。
• 当团队和利益相关者对API设计达成一致时，开发人员使用该文档使用文档生成器工具生成服务器端的骨架代码。
• 最后，开发人员开始使用先前生成的代码在API上工作业务逻辑。

OAS 3.1允许指定HTTP资源、动词、响应代码、数据模型、媒体类型、安全方案和其他API组件。

敏捷开发是软件行业中使用最广泛的方法之一。敏捷意味着尽快构建一个小东西，要么快速失败并更改初始设计，要么逐步添加小的更改继续进行。

从敏捷团队的角度来看，API优先开发有几个优点：

• 提供了一种快速反馈API设计的方式。
• 创建了一个通向API契约协议的单一沟通渠道。
• 允许参与API设计的人员的并行工作。

为了充分理解API优先方法的优势，我们将比较两个敏捷团队的工作流程场景。第一支团队使用传统方法，而第二支使用API优先开发：

4. 定义API契约

我们将使用银行演示REST API来说明API优先方法的工作流程。该API允许两个操作：获取余额和存款金额。为了澄清，下表显示了这些操作的资源路径、HTTP动词和响应代码（RC）：

	HTTP动词	资源	错误RCs	成功RC's
获取余额	GET	/account	404 – 账户未找到	200 – 获取余额信息
存款金额	POST	/account/deposit	404 – 账户未找到	204 – 存款操作完成

现在，我们可以创建OAS API规范文件。我们将使用Swagger在线编辑器，这是一个将YAML解释为Swagger文档的在线解决方案。

4.1. API的顶级上下文

让我们首先定义API的顶级上下文。为此，请转到Swagger编辑器，并用以下YAML代码替换编辑器左侧的内容：

4.2. 公开API路径

现在，让我们创建前面描述的GET /account 和 POST /account/deposit API端点。为此，请在YAML编辑器的根级别添加以下内容：

4.3. 定义数据模型组件

最后，让我们创建我们API的数据模型对象：请求和响应体以及错误消息。为了实现这一点，在YAML编辑器的根级别添加以下结构：

4.4. 查看API文档

此时，API可以在线供产品的利益相关者审查。我们知道API优先开发的主要优势是快速失败或成功的能力，而不会在开发阶段浪费时间。因此，确保每个人在进入开发阶段之前审查和协作提议的API资源、响应代码、数据模型以及API的描述和责任。

一旦团队就设计达成一致，他们就可以并行地在API上工作。

5. 导入到Spring Boot应用程序

本节展示了开发人员如何将YAML文档导入应用程序并自动生成API骨架代码。

首先，我们必须在_/src/main/resources_文件夹中创建一个名为_account_api_description.yaml_的空YAML文件。然后，让我们用Swagger在线编辑器中的完整YAML代码替换_account_api_description.yaml_的内容。最后，我们必须将_openapi-generator-maven-plugin_插件添加到Spring Boot应用程序_pom.xml_文件的_<plugins>_标签中：

6. 结论

在本文中，我们已经看到了如何使用Spring Boot和OAS进行API优先开发。我们还研究了API优先的好处以及它如何帮助现代敏捷软件开发团队。使用API优先的最重要原因是增加敏捷性并减少在创建API时浪费的开发时间。使用这种方法，我们可以起草、迭代更改，并更快地提供设计反馈。

使用API优先方法的另一个好原因是利益相关者不需要依赖开发人员完成代码才能开始他们的工作。 QA、作家、经理和开发人员可以在创建初始API设计文档后并行工作。

如常，你可以在GitHub上找到这里使用的代码。