1、简介 尽管 OpenAPI 3.x 规范自 2017 年起就已发布，并经历了多次更新，但目前许多 API 仍在继续使用旧版本。
本文将带你了解 OpenAPI 2.0 和 OpenAPI 3.0 规范之间的主要区别，以及如何将 OpenAPI 2.0 规范转换为 OpenAPI 3.0。
2、OpenAPI 2.0 和 OpenAPI 3.0 简单回顾一下，OpenAPI 提供了一种标准格式，用于描述人类和机器都能读懂的 HTTP API。在 3.0 版之前，OpenAPI 被称为 Swagger 规范和 Swagger 工具包的一部分。从那时起，它已成为行业标准，并经过多次更新，带来了更多改进和功能。
与 2.0 相比，OpenAPI 3.0 引入了几项根本性变化。
首先，对整体结构进行了重构，以提高可重用性。添加了一个 components（组件）块来组织现有元素（如 schemas、responses、parameters）和新元素（请求 requestBody、examples 和 headers）。一些元素被重新命名 - definitions 现在被称为 schemas，securityDefinitions 被称为 securitySchemes。
此外，OpenAPI 3.0 还进一步扩展了 JSON Schema 功能。添加了 oneOf、anyOf 和 not 等关键字，以便对复杂的数据格式进行描述和灵活验证。
3.0 版本还引入了对 cookie 参数、内容类型协商和回调机制的支持。它还扩展了安全定义并简化了现有流程。
最后，你可以在官方 更新日志 中查看完整的变更列表。
1、概览 文档是构建任何健壮的 REST API 的重要部分。我们可以基于 OpenAPI 规范实现 API 文档，并在 Spring 应用中使用 Swagger UI 进行可视化展示。
此外，由于 API 端点可以通过 API 网关公开，我们还需要将后端服务的 OpenAPI 文档与网关服务集成。网关服务将提供所有 API 文档的汇总视图。
本文将带你了解如何在 Spring 应用中集成 OpenAPI，以及如何使用 Spring Cloud Gateway 服务公开后端服务的 API 文档。
2、示例应用 假设我们需要构建一个简单的微服务来获取一些数据。
2.1、Maven 依赖 首先，添加 spring-boot-starter-web 依赖：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>3.3.2</version> </dependency> 2.2、实现 REST API 我们的后端应用有一个端点返回 Product 数据。
首先，创建 Product 类：
public class Product { private long id; private String name; // 标准 Getter / Setter } 接下来，在 ProductController 中实现 getProduct 端点：
1、简介 本文将带你了解如何在 OpenAPI 文件中声明日期（Date）。特别是在使用 Swagger 实现的情况下，这将使我们能够在调用外部 API 时以标准化的方式管理输入和输出日期。
2、Swagger 和 OAS Swagger 是一组工具，实现了 OpenAPI Specification（OAS），它是一种与编程语言无关的接口，用于文档化 RESTful API。这使我们能够了解任何服务的功能，而无需访问源代码。
要实现这一点，需要在项目中创建一个文件，通常是 YAML 或 JSON，使用 OAS 描述 API。然后，使用 Swagger 工具：
通过浏览器（Swagger 编辑器）编辑规范 自动生成 API 客户库（Swagger Codegen） 显示自动生成的文档（Swagger UI） OpenAPI 文件示例 中包含了不同的部分的示例，本文重点关注模型定义。
3、定义日期（Date） 使用 OAS 定义一个 User 实体：
components: User: type: "object" properties: id: type: integer format: int64 createdAt: type: string format: date description: Creation date example: "2021-01-30" username: type: string 定义日期：
type 等于 string format 字段，指定格式为日期（Date） 在本例中，使用 format: date 来描述 createdAt。这使用 ISO 8601 格式的日期。
1、概览 OpenAPI 是一种与语言无关且独立于平台的规范，用于标准化 REST API。OpenAPI 使用户能够在不深入代码的情况下轻松理解 API。
Swagger-UI 根据 OpenAPI 规范生成可视化文档，帮助可视化和测试 REST API。
本文将带你了解如何在 Spring Boot 应用中使用 Springdoc-OpenAPI 生成 OpenAPI 文档、测试 REST API 并为 OpenAPI 配置 JWT Authentication（认证）。
2、Swagger-UI Swagger-UI 是 HTML、Javascript 和 CSS 文件的集合，可根据 OpenAPI 规范生成 UI 界面。
当 API 数量不断增加时，编写 OpenAPI 文档规范就变得非常具有挑战性。Springdoc-OpenAPI 可以帮助我们自动生成 OpenAPI 文档。
接下来，我们通过示例了解如何使用 Springdoc-OpenAPI 库自动生成 REST API 的 OpenAPI 文档，并使用 Swagger-UI 可视化这些 API。
2.1、依赖 首先，添加 Springdoc-OpenAPI 依赖。
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.9</version> </dependency> 此依赖还将 Swagger-UI web-jar 添加到 Spring Boot 应用中。
1、概览 本文将带你了解如何在 Spring MVC Web 应用中使用 springdoc-openapi 配置默认的全局 Security Scheme，并将其应用为 API 的默认安全配置，以及如何覆盖这些默认的安全配置。
OpenAPI 规范 允许为 API 定义一套 Security Scheme。可以配置 API 全局的安全配置，也可以按端点应用/删除安全配置。
2、设置 构建一个 Spring Boot Web 项目，使用 Maven。
2.1、依赖 该示例有两个依赖。第一个是 spring-boot-starter-web，用于构建 Web 应用。
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>2.7.1</version> </dependency> 另一个依赖是 springdoc-openapi-ui，它用于输出 HTML、JSON 或 YAML 格式的 API 文档：
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.9</version> </dependency> 2.2、启动类 使用 @SpringBootApplication 注解来定义启动类，通过 SpringApplication 类来启动应用：
@SpringBootApplication public class DefaultGlobalSecuritySchemeApplication { public static void main(String[] args) { SpringApplication.run(DefaultGlobalSecuritySchemeApplication.class, args); } } 3、springdoc-openapi 基础配置 配置好 Spring MVC 后，来看看 API 语义信息。
1、概览 Spring REST Docs 和 OpenAPI 3.0 是为 REST API 创建 API 文档的两种方法。
在本教程中，我们将探讨它们的相对优缺点。
2、前世今生 Spring REST Docs 是由 Spring 社区开发的一个框架，用于 为RESTful API 创建准确的文档。它采用了测试驱动的方法，文档可用 Spring MVC tests、Spring Webflux 的 WebTestClient 或 REST-Assured 形式编写。
运行测试的结果会生成 AsciiDoc 文件，可以使用 Asciidoctor 将它们组合在一起，生成描述 API 的 HTML 页面。由于它遵循 TDD 方法，Spring REST Docs 自动带来了许多优势，例如减少代码错误、减少重复工作和更快的反馈周期等。
而，OpenAPI 是一种诞生于 Swagger 2.0 的规范。截至本文撰写时，其最新版本为 3.0，并有许多已知的 实现。
与其他规范一样，OpenAPI 也为其实现制定了一些基本规则。简而言之，所有 OpenAPI 实现都应该以 JSON 或 YAML 格式的 JSON 对象生成文档。
还有 许多工具 可以接收 JSON/YAML，并输出 UI 界面来可视化和导航 API。这在验收测试时非常有用。在这里的代码示例中，我们将使用 Springdoc - 一个用于 OpenAPI 3 和 Spring Boot 的框架。
