網頁

2022/1/28

OpenAPI 文件簡介

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


文件語法

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


最小文件結構

OpenAPI文件包含OpenAPI Specification (OAS)(開放API規格)定義的JSON物件。一個OpenAPI文件的根物件為OpenAPI Object,文件結構至少需包含OpenAPI Object的openapiinfo欄位,及pathscomponetnswebhooks任一。

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


沒有留言:

張貼留言