OpenAPI 的資料型別(type)是基於 Json 擴充，基礎型別有 boolean、integer、number、string......等，並可藉由 format 撰寫更完整的描述，例如：

透過撰寫 format 欄位可以讓型別描述更加明確，由於資料型別在不同語言中不盡相同，越完整的規格越能讓開發者判斷在串接服務時應如何處理該欄位的資料。

除了基礎型別外，type 也包含 array 及 object 兩種方式來描述資料結構。當要描述陣列 (array) 型別時，搭配關鍵字 items 定義該陣列中項目的型別，例如：

# 由整數組成的陣列
type: array
items:
    type: integer

# 由日期時間組成的陣列
type: array
items:
    type: string
    format: datetime

而描述物件 (object) 時，則須搭配關鍵字 properties 描述其中的各個欄位，例如：

# 對應以下 json 的 object
# {
#     "name": "string",
#     "phone": "string",
#     "age": 0,
# }
type: object
properties:
    name:
        type: string
    phone:
        type: string
    age:
        type: integer

物件中若有必填欄位，則使用 required 節點列出所有必填欄位名稱，例如：

# name, phone 為必填欄位
# age 為非必填欄位
type: object
properties:
    name:
        type: string
    phone:
        type: string
    age:
        type: integer
required:
    - name
    - phone

基礎型別、陣列和物件可以組合使用，例如：

# 對應以下 json 的 object
# {
#     "name": "string",
#     "age": 0,
#     "interest": ["swimming", "reading"],
#     "notification":
#     {
#         "email": true,
#         "app": false
#     }
# }
type: object
properties:
    name:
        type: string
    age:
        type: integer
    interest:
        type: array
        items:
            type: string
    notification:
        type: object
        properties:
            email:
                type: boolean
            app:
                type: boolean

# 由物件組成的陣列
type: array
items:
    type: object
    properties:
        name:
            type: string
        age:
            type: integer

理解如何定義資料結構後就可以撰寫 schema 節點，並針對資料結構的各個欄位增加 description 節點增加文字描述，讓文件更完整，例如：

openapi: 3.1.0
info:
  title: 會員服務 API
  description: 提供會員相關服務的 API 介面。
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: 正式環境
  - url: https://api.staging.example.com/v1
    description: 測試環境
paths:
  /members:
    post:
      summary: 註冊新會員
      operationId: registerMember
      requestBody:
        description: 會員註冊資訊
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 姓名
                email:
                  type: string
                  format: email
                  description: 電子郵件
                password:
                  type: string
                  format: password
                  description: 密碼
              required:
                - name
                - email
                - password
        required: true
      responses:
        '201':
          description: 註冊成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  memberId:
                    type: string
                    description: 會員 ID
                required:
                  - memberId
        '400':
          description: 請求格式錯誤

到這邊可能會有些疑問，難道同個自訂型別每次出現在文件中，不能定義一次完整的結構後直接引用嗎？除了型別和說明，有沒有辦法提供範例資料讓文件更完整呢？當然可以！明天將說明如何收斂文件中的結構定義，並撰寫範例資料以完善文件內容。