后端开发教程 - Java、Spring Boot 实战 - msg200.com
为什么要将 REST API 记录为代码？
TL;DR
主题细分
为什么要将 REST API 记录为代码？
什么是 OpenAPI？
OpenAPI 适合于哪里？
工具？
下一步是什么？
进一步阅读
TL;DR
如果您已经熟悉 OpenAPI 及其在应用程序生命周期中的位置，请跳至本博文的核心工具章节。
敬请期待下一篇文章。我将讨论如何使用 OpenAPI 和 Terraform 支持工具来实现。
感谢阅读！
主题细分
为什么要将 REST API 记录为代码？
如今，创建 API 的方法有很多，例如使用Express（Node 环境）、Java Spring等框架，或使用 Amazon Web Services 的API Gateway等云原生解决方案。
我认为单独使用这些解决方案的最大问题是它们没有描述“API 即代码”。你可能会想，我为什么要关心它？以下是几个原因：
- 能够从与编程语言无关的 REST API 定义文件（OpenAPI）生成服务器和客户端代码。
- 作为一种交流工具，它是前端、业务、第三方（公共 API）和后端开发人员均可阅读的文档的基础。
- 遵循基础设施即代码范式，我们可以更轻松地测试和验证 REST API 定义（端点、模型、安全性以及输入输出）。我们可以对 API 定义进行版本控制。
- 开发环境友好，易于生成 REST API 存根并让前端/后端开发人员根据规范进行编程。
- 支持指定 API 端点的输入和输出的正式对象模型规范（例如JSON Schema ）。
- 保持您的实现与正式的 API 规范文档同步。文档很少能与实际情况保持同步。我们通常会忘记在所有变更过程中更新文档。
话虽如此，OpenAPI 提出如何解决这个问题？
什么是 OpenAPI？
良好的设计和编程实践建议使用接口定义。接口定义从高层角度定义了系统或一段代码（模块等）的功能，然后您可以针对该接口进行编程。
这样就实现了实际实现代码与接口代码（广义上的外部世界）的解耦。我们可以自由选择如何实现契约，只要我们满足契约即可。此外，我们通过尽可能多地抽象实现细节（黑盒原则）来简化应用程序设计。
OpenAPI 正是这样做的，它提供了一个接口定义，连接前端应用程序和应用程序的后端“处理/数据存储”部分（典型的 3 层架构情况）。
它通过 REST API 规范文档来实现这一点，该文档以代码（YAML 或 JSON）形式定义 API 端点、数据模型（JSON Schema）等。使用这个与编程语言无关的 API 定义文件，您可以跨应用程序层（前端和后端）生成代码，并根据其 JSON Schema 定义验证输入和输出。
因此，良好且有据可查的接口设计将有利于整个应用程序开发生命周期。
要使所有这些功能协同工作，需要几个步骤。我们将简要介绍以下内容：
- OpenAPI 3 在您的开发过程中处于什么位置？
- 有哪些类型的工具可用？
- 最后，我将在后续博客文章中介绍后续步骤
我暂时不会深入介绍该语言的结构，我会在后续的博客文章中通过一个示例应用程序来介绍。现在，请先阅读这篇简短的说明，了解一下。
OpenAPI 适合于哪里？
大体上，我们可以识别这些应用程序开发阶段，我将把几个阶段放在一起以简化讨论：
- 需求、分析和设计；我们正在构建什么？
- 代码和测试，我们正在构建和测试它。
- 生产维护，正在生产运行中
这里，我们可以根据项目管理风格（敏捷、瀑布等）进行多个阶段的迭代。这又是一个非常广泛的话题。现在，让我们先来思考一下这些阶段，OpenAPI 处于哪个阶段？
需求、分析和设计
在此阶段，前后端开发人员将使用 OpenAPI 就双方需要哪些内容来满足业务和架构需求达成一致。这本身就是一个非常广泛的讨论，OpenAPI 的作用是将设计过程的输出形式化为可在后续开发阶段使用的代码。OpenAPI
还可以形式化安全概念，例如公开访问或需要身份验证的访问，以及扩展。
扩展程序（例如Google Cloud Endpoints、AWS API Gateway）使供应商或公司能够向 API 规范添加“功能”。例如，AWS API Gateway 开发了扩展程序来规范其与后端服务的集成。这意味着，某个端点（例如）可以通过 Velocity 模板直接与 DynamoDB 数据库集成。或者，与LambdaGET /customer/2
等代码执行服务集成。
所有这些都被正式化成一份文档，它既解释了 API 的“为什么”又解释了“怎么做”。接下来就是下一步：编写代码和测试。
代码和测试
在这个阶段，测试人员通常会有一份文档，从业务需求的角度概述测试用例，但必须等到 API 可用后才能进行任何契约测试。有了 OpenAPI 文档，您就可以抢占先机，根据规范（在某个特定点之前）生成测试。
在开发者方面，API 已经可以从 OpenAPI 文档中生成客户端和服务器端的存根。这有助于独立的客户端和服务器端开发。
开发人员和测试人员可以比以往更快地迭代测试和开发合约。此外，客户端和服务器端都可以通过使用内置的 JSON Schema 定义来验证数据模型。
生产与维护
一旦应用程序进入生产和维护阶段，该规范将有效：
- 验证，我们在这里验证 OpenAPi 规范文档与部署内容是否一致。Dredd 等工具可以提供帮助
- 测试，我们打算部署到生产中，它是否按照规范运行？
- 文档，回答以下问题；
- 已经建成了什么，
- 内部和外部的开发人员如何根据 API 规范进行实施。
工具？
现在我们来了解一下 OpenAPI 的核心内容以及我喜欢使用它的原因，即工具！
可能需要几千行代码来指定有关 API 的每一件事，但您所释放的自动化功能会让您难以置信地提高生产力。
那么我们来看看吧。
设计和开发
- Swagger Hub 和 Swagger 编辑器。作为 Swagger/OpenAPI 的创建者，Swagger 通常提供涵盖整个应用程序生命周期的工具。我尤其喜欢他们的编辑器，它可以实时验证规范，并可用作文档/代码生成工具。
- Visual Studio Code。这个编辑器有很多插件可以简化编辑大型 OpenAPI 文档，我使用的插件有：
- 带有树视图的 OpenAPI 编辑器，我非常喜欢这个扩展，因为它将这个庞大的文档分解成一个可以快速导航的树状结构。
- OpenAPI 文档生成，创建您的规范的可视化表示。
- Swagger 查看器，它与 Swagger 编辑器使用的查看器相同。
- OpenAPI Linting
实施框架
我使用过的一些主要框架和云原生解决方案：
- AWS API 网关，您可以使用 IAC 工具或 GUI 导入 Swagger/OpenAPI 文档，它将自动创建端点。OpenAPI规范中有一些特定的AWS 扩展，例如可以添加身份验证以及与 AWS Lambda 的集成。
- Java Spring Boot / Maven 集成，本文介绍了两者之间可能的集成。
- 节点/ ExpressJS
- OpenAPI Enforcer有一个专门的辅助项目，可以自动在你的 Express 应用中生成端点。它还包含通过 OpenAPI 文档中的 JSON Schema 定义进行数据验证的功能，请参阅验证子部分。
代码生成
两者都提供了一组类似的客户端和服务器生成器输出
- OpenAPI Generator，支持的语言和框架见下表。
| 语言/框架 | |
|---|---|
| API 客户端 | ActionScript、Ada、Apex、Bash、C、C#（.net 2.0、3.5 或更高版本、.NET Standard 1.3 - 2.0、.NET Core 2.0）、C++（cpp-restsdk、Qt5、Tizen）、Clojure、Dart（1.x、2.x）、Elixir、Elm、Eiffel、Erlang、Go、Groovy、Haskell（http-client、Servant）、Java（Jersey1.x、Jersey2.x、OkHttp、Retrofit1.x、Retrofit2.x、Feign、RestTemplate、RESTEasy、Vertx、适用于 Java 的 Google API 客户端库、Rest-assured、Spring 5 Web 客户端、MicroProfile Rest Client）、Kotlin、Lua、Nim、Node.js/JavaScript（ES5、ES6、带有 Google Closure Compiler 注释的 AngularJS、Flow 类型）、Objective-C、OCaml、Perl、PHP、PowerShell、 Python、R、Ruby、Rust（rust、rust-server）、Scala（akka、http4s、scalaz、swagger-async-httpclient）、Swift（2.x、3.x、4.x、5.x）、Typescript（AngularJS、Angular（2.x - 8.x）、Aurelia、Axios、Fetch、Inversify、jQuery、Node、Rxjs） |
| 服务器存根 | Ada、C#（ASP.NET Core、NancyFx）、C++（Pistache、Restbed、Qt5 QHTTPEngine）、Erlang、F#（Giraffe）、Go（net/http、Gin）、Haskell（Servant）、Java（MSF4J、Spring、Undertow、JAX-RS：CDI、CXF、Inflector、Jersey、RestEasy、Play Framework、PKMST、Vert.x）、Kotlin（Spring Boot、Ktor、Vertx）、PHP（Laravel、Lumen、Slim、Silex、Symfony、Zend Expressive）、Python（Flask）、NodeJS、Ruby（Sinatra、Rails5）、Rust（rust-server）、Scala（Finch、Lagom、Play、Scalatra） |
- Swagger CodeGen和Github支持的语言和框架较少，但可能完全符合您的需求。
| 语言/框架 | |
|---|---|
| API 客户端 | ActionScript、Ada、Apex、Bash、C#（.net 2.0、3.5 或更高版本）、C++（cpprest、Qt5、Tizen）、Clojure、Dart、Elixir、Elm、Eiffel、Erlang、Go、Groovy、Haskell（http-client、Servant）、Java（Jersey1.x、Jersey2.x、OkHttp、Retrofit1.x、Retrofit2.x、Feign、RestTemplate、RESTEasy、Vertx、适用于 Java 的 Google API 客户端库、Rest-assured）、Kotlin、Lua、Node.js（ES5、ES6、带有 Google Closure Compiler 注释的 AngularJS）Objective-C、Perl、PHP、PowerShell、Python、R、Ruby、Rust（rust、rust-server）、Scala（akka、http4s、swagger-async-httpclient）、Swift（2.x、3.x、4.x、5.x）、Typescript （Angular1.x、Angular2.x、Fetch、jQuery、Node） |
| 服务器存根 | Ada、C#（ASP.NET Core、NancyFx）、C++（Pistache、Restbed）、Erlang、Go、Haskell（Servant）、Java（MSF4J、Spring、Undertow、JAX-RS：CDI、CXF、Inflector、RestEasy、Play Framework、PKMST）、Kotlin、PHP（Lumen、Slim、Silex、Symfony、Zend Expressive）、Python（Flask）、NodeJS、Ruby（Sinatra、Rails5）、Rust（rust-server）、Scala（Finch、Lagom、Scalatra） |
验证和测试
- Dredd是一个 CLI 工具/JavaScript 库，可以根据正在运行的服务器验证你的规范。OpenAPI 3 支持仍处于实验阶段 (!)
- OpenAPI Enforcer，服务器端 Node（可选 Express）的验证库。
- Swagger 测试生成会自动为特定的 HTTP 状态代码创建测试用例，并且还可以进行负载测试。
- JSON Schema 验证器/生成器/测试，存在许多基于 JSON Schema 进行验证、生成和测试的工具。
下一步是什么？
下周我将使用Terraform和 AWS API Gateway 演示如何使用 OpenAPI 规范创建带有验证的服务器端 REST API。
如果这篇文章对您有用，请在下面的评论中告诉我，以及您还想阅读什么内容。
如果您已经在使用 OpenAPI，请在评论中告诉我您的使用体验。
感谢您的阅读，下周再见！
进一步阅读
- OpenAPI 和 Swagger 之间的区别
- OpenAPI 工具
- OpenAPI 3.0.2 规范
- OpenAPI的基本结构
- 为什么 API 文档很重要
- 如何在 Spring Boot 中使用 OpenAPI
- API 设计与代码优先
- JSON Schema 客户端验证
- JSON Schema 服务器端验证
- 什么是 Swagger 以及为什么需要它？
- JSON Schema 实现