完成服務的基本描述後，就可以針對各支 API 內容進行撰寫了。同樣以虛構的會員服務為範例，以下是一支「取得單一會員資訊 API」的 OpenAPI 規格：

# 以上省略
paths:
  /members/{memberId}:
    get:
      summary: 取得單一會員資訊
      description: 查詢指定會員的資訊，若該會員不存在時回應 `404 Not Found`。
      operationId: getMember
      parameters:
        - name: memberId
          in: path
          required: true
          description: 會員 ID
          schema:
            type: string
      responses:
        '200':
          description: 成功取得會員資訊
          content:
            application/json:
              schema:
                type: object
                properties:
                  memberId:
                    type: string
                    example: "abc123"
                  name:
                    type: string
                    example: "張三"
                  email:
                    type: string
                    format: email
                    example: "zhangsan@example.com"
        '404':
          description: 會員未找到
# 以下省略

在 path 節點下定義 API 的路由，每個路由可對應到多個 HTTP Method，到這個節點即為一支 API，可以撰寫這支 API 的相關規格。operationId 節點可設定每支 API 的 Id，正常情況下整份文件內的 operationId 不應重複。summary 節點可設定這支 API 的簡稱，而 description 節點內容為這支 API 的說明，和 info.description 一樣支援 markdown 語法。

接著在 parameters 節點內定義 Request 的參數：

• name：參數的名稱，必填。
• in：參數的位置，應為 path、query、header 或 coockie 之一，必填。
• required：是否為必填參數，應為布林值。
• description：參數的說明，支援 markdown 語法。
• schema：參數的結構，詳細內容將在明日說明。

完成了 Request 規格後，就可以處理 Response 的部分了。一支 API 可使用不同的 Response Status Code 定義在 responses 節點下，並以 description 描寫各自的情境。content 中則會說明 Response 的多媒體類型，如：application/json、image、text/plain ......等。

到這邊，我們已經完成虛構的會員服務基礎的 API 規格文件如下：

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
                  example: "張三"
                email:
                  type: string
                  format: email
                  example: "zhangsan@example.com"
                password:
                  type: string
                  format: password
                  example: "password123"
              required:
                - name
                - email
                - password
        required: true
      responses:
        '201':
          description: 註冊成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  memberId:
                    type: string
                    example: "abc123"
        '400':
          description: 請求格式錯誤

  /members/{memberId}:
    get:
      summary: 取得單一會員資訊
      description: 查詢指定會員的資訊，若該會員不存在時回應 `404 Not Found`。
      operationId: getMember
      parameters:
        - name: memberId
          in: path
          required: true
          description: 會員 ID
          schema:
            type: string
      responses:
        '200':
          description: 成功取得會員資訊
          content:
            application/json:
              schema:
                type: object
                properties:
                  memberId:
                    type: string
                    example: "abc123"
                  name:
                    type: string
                    example: "張三"
                  email:
                    type: string
                    format: email
                    example: "zhangsan@example.com"
                  createdAt:
                    type: string
                    format: date-time
                    example: "2022-01-01T00:00:00Z"
        '404':
          description: 會員未找到

    delete:
      summary: 註銷會員
      operationId: deleteMember
      parameters:
        - name: memberId
          in: path
          required: true
          description: 會員 ID
          schema:
            type: string
      responses:
        '204':
          description: 成功註銷會員
        '404':
          description: 會員未找到

  /members/list:
    get:
      summary: 取得多筆會員資訊
      operationId: listMembers
      parameters:
        - name: limit
          in: query
          description: 限制返回的會員數量
          schema:
            type: integer
            example: 10
        - name: offset
          in: query
          description: 分頁偏移量
          schema:
            type: integer
            example: 0
      responses:
        '200':
          description: 成功取得會員列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    items:
                      type: object
                      properties:
                        memberId:
                          type: string
                          example: "abc123"
                        name:
                          type: string
                          example: "張三"
                        email:
                          type: string
                          format: email
                          example: "zhangsan@example.com"
                        createdAt:
                          type: string
                          format: date-time
                          example: "2022-01-01T00:00:00Z"
                  totalCount:
                    type: integer
                    example: 100
        '400':
          description: 請求格式錯誤

可將這份文件透過 Swagger UI、Redoc 或其他支援 OpenAPI 的視覺化工具呈現，下圖為虛構會員服務的 Redoc 畫面：

明天，將針對 OpenAPI 的資料型別及 schema 節點規範進行說明。