介绍
在使用 OpenAPI 和 Spring Boot 工作几年后，我发现一些经验丰富的开发人员不知道这种方法。
在我的最近的项目中，我使用 OpenAPI 规范生成了 DTO 对象和 Spring Boot 上 RestController 的接口，前端团队使用 OpenAPI 规范创建了对象和 API 的客户端。
本文将解释 OpenAPI 和 Spring Boot 如何共同使用 API First Concept。
OpenAPI
在 官方 网站上：
OpenAPI 规范（OAS）定义了一种标准的、与语言无关的 RESTful API 接口，允许人类和计算机发现和理解服务的功能，而无需访问源代码、文档或通过网络流量检查。当正确定义时，消费者可以使用最少的实现逻辑理解和与远程服务交互。
下面是符合 OpenAPI 规范的 POST、GET、PATCH 和 DELETE 请求/响应，包括多部分和路径参数。因此，它很简单易读，但是 Swagger 编辑器 更简单，更适合测试和编码。
符合 OpenAPI 规范的 OpenAPI 文档本身是一个 JSON 对象，可以使用 JSON 或 YAML 格式表示。
OpenAPI 规范
一开始可能会感到困惑，但是由于使用 YAML 的声明性编写规范的方式变得非常直观和易读。尽管如此，有许多工具可以帮助这个过程。
在我看来，最重要的部分是：
项目结构
在这个例子中，项目结构是一个父 pom 和 2 个模块：一个是规范（openapi.yaml），另一个是实现（这个规范），称为 impl.
项目结构的屏幕截图
OpenAPI Generator
为了自动生成 DTO 对象和 Rest 接口，我们可以使用插件 openapi-generator-maven-plugin（对于 Gradle，使用此插件 — 感谢 Aleksandar Stoisavljevic）。使用此插件的 POM 的示例：
这个定义将生成这些类：
在实现中，我们向这个模块添加一个依赖项。
<dependency>
<groupId>io.xgeeks.demo.api</groupId>
<artifactId>first-api-spec</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
在完美的环境中，这个工件将被推送到类似 Nexus、JFrog、GitLab、Github 这样的工件管理器中...
实现
REST 方法的签名由 API 规范本身定义。在我看来，这是从后端使用 OpenAPI Generator 实现 API First Approach 的最大优势。让我们看看 UserApi 接口（由 OpenAPI Generator 生成）
自动生成的接口
这是一种保持前端、后端和第三方应用程序之间规范信心的方式。响应、负载、参数、映射等都由 OpenAPI 定义。因此，在我的模块实现（first-api-impl）中，我只需要实现之前生成的接口中的所有方法：
你可以在我的 Github 上查看并使用我的演示：
GitHub - mEstrazulas/demo-api-first: An API first application using Spring Boot and OpenAPI 3
前端呢？
在我的上一个项目中，前端使用了一个自动生成的 React 插件来自动生成客户端和类型。在 这个网站 上，可以查看多种技术和编程语言的客户端生成器列表。
API First 方法使前端人员可以使用 MockServer 和 OpenAPI 规范。当后端部分尚未完全实现测试时，这样可以加快速度。
GitHub - muonsoft/openapi-mock: OpenAPI mock server with random data generation
自动生成的客户端
使用 Swagger-Codegen 插件，可以自动生成依赖于规范的客户端。这将帮助使用 HTTP 请求之间的分布式系统之间的通信。在本文中，我们不涉及此问题，但这里有相关信息。为什么要使用这种方法而不是其他方法？（由Luis Nina提供）
在我看来，这种方法有两个主要目的：1. 帮助后端定义应该实现的正确方法，对于前端来说，让他们以自己的步伐前进，而不必完全实现API；2. 另一个主要目的（不仅限于这种方法，而是OpenAPI通常）是这种规范创建了感兴趣的各方之间的契约，只要团队遵守规范，他们就可以使用多种工具和技术。
为什么要使用这种方法而不是其他方法？（由Micael Vianna提供）
除了Luis Nina所说的之外，API First还允许开发人员更好地思考应用程序，在部署之前与其他团队进行协商，而不会导致接触等待。
参考文献：
- https://openapi-generator.tech/docs/generators/
- https://editor.swagger.io/
- https://swagger.io/docs/specification/about/
- https://swagger.io/docs/specification/data-models/data-types/
- https://github.com/mEstrazulas/demo-api-first
- https://www.mock-server.com/mock_server/using_openapi.html
- https://github.com/muonsoft/openapi-mock
- https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin
- https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen-maven-plugin/
- https://www.baeldung.com/spring-boot-rest-client-swagger-codegen#1-maven-plugin
译自：https://medium.com/xgeeks/api-first-using-openapi-and-spring-boot-2602c04bb0d3
评论(0)