[ADP-764] OpenAPI 格式約定
概述
OpenAPI 規範使用 JSON Schema 的一個子集來定義數據類型。這包括使用 format 關鍵字來提供關於值應如何被解釋的額外資訊。
指導原則
應該(SHOULD)使用標準的 OpenAPI 格式或自定義的 JSON Schema 格式。
自定義格式應該(SHOULD)在 API 規範中明確記錄。
選擇最適合每種數據類型的格式。
當擴展或創建新格式時，遵循 ADP-754 中的原則。
常見格式
| 格式 | 描述 | 示例 |
|---|---|---|
| date | 完整日期 | 2024-07-21 |
| date-time | 日期和時間（時區偏移） | 2024-07-21T17:32:28Z |
| time | 一天中的時間 | 17:32:28 |
| duration | 持續時間 | P1DT2H |
| 電子郵件地址 | user@example.com | |
| idn-email | 國際化電子郵件地址 | 用戶@例子.com |
| hostname | 互聯網主機名 | example.com |
| idn-hostname | 國際化主機名 | 例子.com |
| ipv4 | IPv4 地址 | 192.0.2.1 |
| ipv6 | IPv6 地址 | 2001:db8::1 |
| uri | URI | https://example.com/foo?bar=baz |
| uri-reference | URI 引用 | /foo?bar=baz |
| iri | 國際化 URI | https://例子.com/foo?bar=baz |
| iri-reference | 國際化 URI 引用 | /foo?bar=baz |
| uuid | 通用唯一標識符 | 123e4567-e89b-12d3-a456-426614174000 |
| json-pointer | JSON 指針 | /foo/bar/0 |
| relative-json-pointer | 相對 JSON 指針 | 2/foo/bar/0 |
| regex | 正則表達式 | ^[a-z]+$ |