openapi

在 OpenAPI 文件中声明日期

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 格式的日期。

给 OpenAPI 配置 JWT Authentication(认证)

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 应用中。

springdoc-openapi 定义全局的默认 SecurityScheme

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 语义信息。

Spring REST Docs 与 OpenAPI 的比较

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 的框架。