知識庫 / Spring / Spring Web RSS 訂閱

1. 引言

在本教程中，我們將學習如何在 OpenAPI 文件中聲明日期，這裏以 Swagger 為例。這將使我們能夠以標準化的方式管理調用外部 API 時輸入和輸出的日期。

2. Swagger 與 OAS

Swagger 是一個工具集，它實現了 OpenAPI 規範 (OAS)，這是一種語言無關的 RESTful API 文檔化接口。 這樣，我們可以在不訪問源代碼的情況下，瞭解任何服務的能力。

為了實現這一點，我們將在項目中創建一個文件，通常是 YAML 或 JSON，該文件使用 OAS 來描述 API。 然後，我們將使用 Swagger 工具來：

• 通過瀏覽器（Swagger 編輯器）編輯我們的規範
• 自動生成 API 客户端庫（Swagger Codegen）
• 顯示自動生成的文檔（Swagger UI）

OpenAPI 文件示例 包含不同的部分，但我們將重點關注模型定義。

3. 定義日期

讓我們使用 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 格式來描述 createdAt 日期。該格式使用 ISO 8601 full-date 格式描述日期。

4. 定義日期時間

此外，如果我們還想指定時間，我們將使用 date-time 作為格式。 讓我們來看一個例子：

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

在本例中，我們使用 ISO 8601 完整 時間 格式來描述日期和時間。

5. 模式 字段

使用 OAS，我們可以描述其他格式的日期。要做到這一點，我們使用 模式 字段：

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

顯然，這是一種可讀性較差的方法，但功能最強大。事實上，我們可以使用任何正則表達式。

6. 結論

在本文中，我們學習瞭如何使用 OpenAPI 聲明日期。我們可以使用 OpenAPI 提供的標準格式，也可以使用自定義模式以滿足我們的需求。