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

4、定义日期时间（DateTime）

如果还想指定时间，可以使用 format: date-time。

createdAt:
  type: string
  format: date-time
  description: Creation date and time
  example: "2021-01-30T08:30:00Z"

同样，也使用 ISO 8601 格式的日期时间。

5、 pattern 字段

还可以使用 pattern 字段来描述其他格式的日期。

customDate: 
  type: string 
  pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])

显然，这种方法的可读性较差，但功能却最强大。可以在这个字段中使用任何正则表达式。

6、总结

本文介绍例如如何使用 OpenAPI 声明日期，可以使用 OpenAPI 提供的标准格式以及自定义 pattern 来满足需求。

Ref：https://www.baeldung.com/openapi-dates