昨天探討了 Web API 文件要有的內容，OpenAPI 提供了標準化的規範，讓開發者能夠以 json 或 yaml 格式來描述 API 規格。不少開發者都有看過或用過 Swagger (如下圖)，Swagger 其實分為 Swagger UI 及 Swagger Specification 兩個部分，OpenAPI 即為 Swagger Specification 2.0 後改名而來。OpenAPI 規範目前最新版本為 3.1.0，接下將以這個版本及以虛構的會員服務做為範例，說明 OpenAPI 中的各節點定義。

以下範例僅針對必填欄位及部分個人常用欄位介紹，完整規格定義請見 OpenAPI Specification v3.1.0。

openapi: 3.1.0
info:
  title: 會員服務 API
  description: 提供會員註冊、查詢和註銷的服務
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: 正式環境
  - url: https://api.staging.example.com/v1
    description: 測試環境
# 以下省略

OpenAPI 可以用 json 或 yaml 呈現，文件開頭必須以 openapi 節點告其 OpenAPI 版本，並在 info 節點定義此服務的基本資訊，其中標題 (info.title) 及版本 (info.version) 為必填，這邊的版本指的是應用服務的版本，與 OpenAPI 版本是獨立的。應用服務的描述可寫在 info.description 節點，若篇幅較長有排版需求可使用 markdown 語法撰寫，參考範例如下：

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: 測試環境
# 以下省略

接著可以在 servers 節點中定義提供應用服務的伺服器資訊，像是網址及其名稱。這個節點可以列多個伺服器，若服務有多環境或多地區提供相同服務，可以統一在這邊列出。

至此，服務的基礎資訊都有了，明天將介紹在 OpenAPI 中如何撰寫一支 API 的細節規格。