OpenAPI 文件中的日期定义

1. 简介

本文将介绍如何在 OpenAPI 规范文件中正确地声明日期类型，特别是在使用 Swagger 实现时的实践方式。通过标准化日期格式的定义，我们可以在调用外部 API 时统一处理输入和输出的日期数据，避免因格式不一致导致的“踩坑”。

这在微服务间通信、API 文档自动生成以及前后端协作中尤为重要。

2. Swagger 与 OAS 的关系

Swagger 是一套基于 OpenAPI Specification（简称 OAS）的工具链，用于描述和实现 RESTful API 的标准化文档。OAS 是语言无关的接口规范，让我们无需查看源码也能理解一个服务的能力。

在项目中，我们通常会维护一个 YAML 或 JSON 格式的 OpenAPI 文件，它遵循 OAS 规范。然后通过 Swagger 提供的工具来：

✅ 使用 Swagger Editor 在浏览器中可视化编辑 API 定义
✅ 利用 Swagger Codegen 自动生成客户端 SDK
✅ 通过 Swagger UI 展示交互式 API 文档

虽然 OpenAPI 文件包含多个部分（如 paths、security、servers 等），但本文重点关注 模型定义（components/schemas） 中的日期字段声明。

3. 定义日期（Date）

假设我们有一个 User 实体，需要表示其创建日期。在 OpenAPI 中，日期应使用字符串类型配合特定格式来声明：

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：表示这是一个 ISO 8601 标准的“全日期”格式（即 YYYY-MM-DD）
✅ example 提供示例值，便于前端或测试理解

⚠️ 注意：不要用 type: number 或自定义类型来表示日期，这会破坏跨平台兼容性。

4. 定义日期时间（Date-Time）

如果需要精确到时间（含时区），应使用 date-time 格式：

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

说明：

✅ format: date-time 遵循 ISO 8601 的完整时间格式
✅ 示例中的 T 分隔日期与时间，Z 表示 UTC 时区（零时区）
✅ 支持带偏移量的时间，例如 2021-01-30T08:30:00+08:00

这种格式被大多数现代框架（如 Spring Boot、Jackson）原生支持，解析时可直接映射为 java.time.Instant 或 OffsetDateTime。

5. 使用 pattern 字段自定义日期格式

有时候业务要求使用非标准格式（比如 yyyyMMdd），这时可以通过 pattern 字段配合正则表达式来约束：

customDate: 
  type: string 
  pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
  description: Custom date 
  example: "20210130"

特点：

✅ 完全自由：可定义任意格式，如 dd/MM/yyyy、yyyy.MM.dd
❌ 可读性差：正则表达式对新人不友好
❌ 工具支持弱：部分客户端生成工具可能无法正确处理非标准格式

✅ 建议：除非有 legacy 系统对接需求，否则优先使用标准 date 或 date-time。

6. 总结

在 OpenAPI 中定义日期时，推荐遵循以下原则：

场景	推荐方式
仅日期（如生日、注册日）	`type: string`, `format: date`
精确时间（含时分秒）	`type: string`, `format: date-time`
特殊格式（兼容老系统）	`pattern` + 正则

✅ 最佳实践：统一使用 ISO 8601 标准格式，减少前后端沟通成本，避免时区歧义。

示例代码已整理至 GitHub：https://github.com/baeldung/tutorials/tree/master/spring-web-modules/spring-rest-http

Persistence

REST

Security