OpenAPI 文件簡介

OpenAPI文件(OpenAPI document)是用來描述HTTP類API的檔案，簡介如下。

文件語法

OpenAPI是以JSON物件表示的JSON或YAML文字檔，根文件通常稱為openapi.json或openapi.yaml，且可分割成多個JSON或YAML檔。

最小文件結構

OpenAPI文件包含OpenAPI Specification (OAS)（開放API規格）定義的JSON物件。一個OpenAPI文件的根物件為OpenAPI Object，文件結構至少需包含OpenAPI Object的openapi及info欄位，及paths、componetns、webhooks任一。

• root: 根物件OpenAPI Object。
  • openapi: string。OAS版本，例如"3.1.0"
  • info: Info Object。提供API的一般資訊如標題、版本、敘述、作者、聯絡資訊。標題(title)和版本(version)為必要欄位。
    • title: string。API文件的名稱。
    • version: string。API文件的版本。
• paths: Paths Object。描述API的endpoints，包括資源路徑、路徑參數，API敘述、操作及回應等。

最小OpenAPI文件YAML範例：

openapi: 3.1.0
info:
  title: A minimal OpenAPI document
  version: 0.0.1
paths: {} # No endpoints defined

最小OpenAPI文件JSON範例：

{
  "openapi": "3.1.0",
  "info": {
    "title": "A minimal OpenAPI document",
    "version": "0.0.1"
  },
  "paths": {}
}

簡單範例

參考「OpenAPI 簡單範例」。

• Structure of an OpenAPI Document
• OpenAPI和Swagger的差別
• 什麼是Contract-first API development？