[ADP-765] OpenAPI: 時區格式
概述
OpenAPI 架構並未將時區數據作為默認格式涵蓋在內。為解決這個問題，我們引入了一個基於 IANA tzdata 的新格式。
指導原則
- 必須(MUST)使用自定義的
iana-timezone數據格式（例如，"America/New_York"、"Europe/London"）。 - 必須(MUST)表示為字符串類型。
- 應(SHOULD)在架構中提供有效時區值的示例。
- 應(SHOULD)包含說明，解釋預期格式和任何限制。
實施
架構定義
yaml
components:
schemas:
Timezone:
type: string
format: iana-timezone
description: IANA 格式的時區
example: "America/New_York"使用示例
yaml
openapi: 3.1.0
info:
title: 時區 API
version: 1.0.0
paths:
/example:
get:
summary: 示例端點
responses:
'200':
description: 成功回應
content:
application/json:
schema:
type: object
properties:
timezone:
$ref: '#/components/schemas/Timezone'