[ADP-766] OpenAPI: 國家代碼格式

指導方針

• 必須(MUST)使用 ISO 3166-1 alpha-2 標準作為國家代碼。
• 應該(SHOULD)使用 iso-country-code 格式來表示國家代碼的字串欄位。
• 必須(MUST)為國家代碼欄位包含清晰的描述。
• 應該(SHOULD)為國家代碼欄位提供示例值。

OpenAPI 架構

使用以下架構來定義國家代碼欄位:

openapi: 3.1.0
info:
  title: 國家代碼 API
  version: 1.0.0
paths:
  /example:
    get:
      summary: 示例端點
      responses:
        '200':
          description: 成功回應
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountryCodeResponse'
components:
  schemas:
    CountryCodeResponse:
      type: object
      properties:
        countryCode:
          type: string
          format: iso-country-code
          description: ISO 3166-1 alpha-2 國家代碼
          example: "US"

參考資料

設計參考

• https://api.otto.de/portal/guidelines/r100071