網頁

▼

2022/1/28

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 簡單範例」。


沒有留言:

張貼留言