OpenAPI 規格

版本 3.0.3

當且僅當本文檔中的關鍵字「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「NOT RECOMMENDED」、「MAY」和「OPTIONAL」以全部大寫形式顯示時，才應按照 BCP 14 RFC2119 RFC8174 中的描述進行解釋，如這裡所示。

本文件依據 Apache 授權條款 2.0 版授權。

簡介

OpenAPI 規格 (OAS) 定義了 RESTful API 的標準、與語言無關的介面，這讓人類和電腦都能夠在無需存取原始碼、文件或透過網路流量檢查的情況下，探索和了解服務的功能。在經過適當定義後，消費者可以透過最少的實作邏輯來理解遠端服務並與其互動。

然後，文件產生工具可以使用 OpenAPI 定義來顯示 API、程式碼產生工具可以使用 OpenAPI 定義來產生各種程式語言的伺服器和用戶端、測試工具和許多其他用例。

定義

OpenAPI 文件

定義或描述 API 的文件（或一組文件）。OpenAPI 定義使用並符合 OpenAPI 規格。

路徑樣板

路徑樣板指的是使用花括號 ({}) 分隔的樣板表達式，將 URL 路徑的一部分標記為可使用路徑參數替換。

路徑中的每個樣板表達式都必須對應一個路徑參數，該參數包含在路徑項目本身中和/或每個路徑項目的操作中。

媒體類型

媒體類型定義散布在多個資源中。媒體類型定義應符合 RFC6838。

一些可能的媒體類型定義範例

  text/plain; charset=utf-8
  application/json
  application/vnd.github+json
  application/vnd.github.v3+json
  application/vnd.github.v3.raw+json
  application/vnd.github.v3.text+json
  application/vnd.github.v3.html+json
  application/vnd.github.v3.full+json
  application/vnd.github.v3.diff
  application/vnd.github.v3.patch

HTTP 狀態碼

HTTP 狀態碼用於指示執行操作的狀態。可用狀態碼由 RFC7231 定義，而註冊的狀態碼列在 IANA 狀態碼註冊表中。

規格

版本

OpenAPI 規格使用語意版本控制 2.0.0 (semver) 進行版本控制，並遵循 semver 規格。

semver 的 major.minor 部分（例如 3.0）應指定 OAS 功能集。通常，.patch 版本會處理此文件中的錯誤，而不是功能集。支援 OAS 3.0 的工具應與所有 OAS 3.0.* 版本相容。工具不應考慮修補程式版本，因此例如 3.0.0 和 3.0.1 之間沒有區別。

每個 OpenAPI 規格的新次要版本都應允許任何對同一主要版本中任何先前的規格次要版本有效的 OpenAPI 文件，都可更新為具有對等語意的新規格版本。此類更新僅需將 openapi 屬性變更為新的次要版本即可。

例如，有效的 OpenAPI 3.0.2 文件在將其 openapi 屬性變更為 3.1.0 後，應為有效的 OpenAPI 3.1.0 文件，其語意等同於原始 OpenAPI 3.0.2 文件。必須編寫 OpenAPI 規格的新次要版本，以確保這種形式的向後相容性。

與 OAS 3.*.* 相容的 OpenAPI 文件包含必要的 openapi 欄位，該欄位指定其使用的 OAS 語意版本。(OAS 2.0 文件包含一個名為 swagger 和值為 "2.0" 的最上層版本欄位。)

格式

符合 OpenAPI 規格的 OpenAPI 文件本身是一個 JSON 物件，可以使用 JSON 或 YAML 格式表示。

例如，如果欄位具有陣列值，則將使用 JSON 陣列表示

{
   "field": [ 1, 2, 3 ]
}

規格中的所有欄位名稱都區分大小寫。這包括所有用作對應中鍵的欄位，除非明確指出鍵不區分大小寫。

結構描述會公開兩種欄位類型：具有宣告名稱的固定欄位和宣告欄位名稱的 regex 模式的圖樣欄位。

圖樣欄位在包含物件中必須具有唯一名稱。

為了保留 YAML 和 JSON 格式之間的往返能力，建議使用 YAML 版本 1.2 以及一些額外限制

標籤必須限制為 JSON 結構描述規則集所允許的標籤。
YAML 對應中使用的鍵必須限制為標量字串，如 YAML Failsafe 結構描述規則集所定義。

注意：雖然 API 可以透過 YAML 或 JSON 格式的 OpenAPI 文件定義，但 API 請求和回應主體以及其他內容不一定要是 JSON 或 YAML。

文件結構

OpenAPI 文件可以由單一文件組成，也可以由使用者自行決定劃分為多個連線的部分。在後一種情況下，必須在規格中使用 $ref 欄位，以根據 JSON 結構描述定義參照這些部分。

建議將根 OpenAPI 文件命名為：openapi.json 或 openapi.yaml。

資料類型

OAS 中的基本資料類型基於 JSON 結構描述規格 Wright 草稿 00支援的類型。請注意，也支援 integer 作為類型，並定義為沒有分數或指數部分的 JSON 數字。不支援 null 作為類型（請參閱 nullable 以取得替代解決方案）。模型使用結構描述物件定義，這是 JSON 結構描述規格 Wright 草稿 00 的擴充子集。

基本類型具有選擇性的修飾符屬性：format。OAS 使用多種已知格式來詳細定義正在使用的資料類型。但是，為了支援文件需求，format 屬性是一個開放的 string 值屬性，可以具有任何值。即使此規格未定義 "email"、"uuid" 等格式，也可能會使用這些格式。沒有 format 屬性的類型會遵循 JSON 結構描述中的類型定義。不辨識特定 format 的工具可能會回復為僅使用 type，就像沒有指定 format 一樣。

OAS 定義的格式為

`類型`	`格式`	註解
`整數`	`int32`	帶正負號的 32 位元
`整數`	`int64`	帶正負號的 64 位元（又名長整數）
`數字`	`float`
`數字`	`雙精度浮點數`
`字串`
`字串`	`位元組`	base64 編碼字元
`字串`	`二進位`	任何位元組序列
`布林值`
`字串`	`日期`	如 `full-date` 所定義 - RFC3339
`字串`	`日期時間`	如 `date-time` 所定義 - RFC3339
`字串`	`密碼`	提示 UI 隱藏輸入。

豐富文字格式設定

在整個規格中，description 欄位都被標註為支援 CommonMark markdown 格式。當 OpenAPI 工具呈現富文本時，它必須至少支援 CommonMark 0.27 所描述的 markdown 語法。工具可以選擇忽略某些 CommonMark 功能以解決安全問題。

URL 中的相對參考

除非另有說明，所有 URL 屬性都可以是 RFC3986 中定義的相對參考。相對參考會使用 Server Object 中定義的 URL 作為基本 URI 來解析。

$ref 中使用的相對參考會依照 JSON Reference 處理，並使用當前文件的 URL 作為基本 URI。另請參閱參考物件。

結構描述

在以下描述中，如果某個欄位沒有明確標示為必要 (REQUIRED) 或以 MUST 或 SHALL 描述，則可以視為可選 (OPTIONAL)。

OpenAPI 物件

這是 OpenAPI 文件的根文件物件。

固定欄位

欄位名稱	類型	描述
openapi	`字串`	必要 (REQUIRED)。這個字串必須是 OpenAPI 文件使用的 OpenAPI 規格版本的語義版本號。`openapi` 欄位應該由工具規格和客戶端使用，以解釋 OpenAPI 文件。這與 API 的 `info.version` 字串無關。
info	資訊物件	必要 (REQUIRED)。提供有關 API 的元數據。元數據可以根據需要由工具使用。
servers	[伺服器物件]	伺服器物件的陣列，提供與目標伺服器的連線資訊。如果未提供 `servers` 屬性，或為空陣列，則預設值將是伺服器物件，其 url 值為 `/`。
paths	路徑物件	必要 (REQUIRED)。API 的可用路徑和操作。
components	元件物件	用於保存規格的各種架構的元素。
security	[安全需求物件]	聲明可以在整個 API 中使用的安全機制。值列表包括可使用的替代安全需求物件。只需要滿足其中一個安全需求物件即可授權請求。個別操作可以覆寫此定義。若要使安全性可選，可以在陣列中包含一個空的安全需求 (`{}`)。
tags	[標籤物件]	規格使用的標籤列表，帶有額外的元數據。標籤的順序可以用於反映解析工具的順序。並非操作物件使用的所有標籤都必須聲明。未聲明的標籤可以隨機組織或基於工具的邏輯。列表中每個標籤名稱必須是唯一的。
externalDocs	外部文件物件	額外的外部文件。

這個物件可以透過規格擴展進行擴充。

資訊物件

這個物件提供關於 API 的元數據。元數據可以根據客戶端需要使用，並且可以為了方便在編輯或文件生成工具中呈現。

固定欄位

欄位名稱	類型	描述
title	`字串`	必要 (REQUIRED)。API 的標題。
description	`字串`	API 的簡短描述。CommonMark 語法可以用於富文本表示。
termsOfService	`字串`	API 服務條款的 URL。必須採用 URL 格式。
contact	聯絡人物件	公開 API 的聯絡資訊。
license	授權物件	公開 API 的授權資訊。
version	`字串`	必要 (REQUIRED)。OpenAPI 文件的版本 (這與 OpenAPI 規格版本或 API 實作版本不同)。

這個物件可以透過規格擴展進行擴充。

資訊物件範例

{
  "title": "Sample Pet Store App",
  "description": "This is a sample server for a pet store.",
  "termsOfService": "http://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "http://www.example.com/support",
    "email": "[email protected]"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
  name: API Support
  url: http://www.example.com/support
  email: [email protected]
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

聯絡人物件

公開 API 的聯絡資訊。

固定欄位

欄位名稱	類型	描述
name	`字串`	聯絡人/組織的識別名稱。
url	`字串`	指向聯絡資訊的 URL。必須採用 URL 格式。
email	`字串`	聯絡人/組織的電子郵件地址。必須採用電子郵件地址格式。

這個物件可以透過規格擴展進行擴充。

聯絡物件範例

{
  "name": "API Support",
  "url": "http://www.example.com/support",
  "email": "[email protected]"
}

name: API Support
url: http://www.example.com/support
email: [email protected]

授權物件

公開 API 的授權資訊。

固定欄位

欄位名稱	類型	描述
name	`字串`	必要 (REQUIRED)。用於 API 的授權名稱。
url	`字串`	API 使用的授權的 URL。必須採用 URL 格式。

這個物件可以透過規格擴展進行擴充。

授權物件範例

{
  "name": "Apache 2.0",
  "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
}

name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html

伺服器物件

表示伺服器的物件。

固定欄位

欄位名稱	類型	描述
url	`字串`	必要 (REQUIRED)。目標主機的 URL。此 URL 支援伺服器變數，並且可以是相對的，以表示主機位置相對於 OpenAPI 文件服務的位置。當變數在 `{`大括號`}` 中命名時，將進行變數替換。
description	`字串`	一個可選字串，描述由 URL 指定的主機。CommonMark 語法可以用於富文本表示。
variables	Map[`string`, 伺服器變數物件]	變數名稱與其值之間的映射。該值用於伺服器 URL 範本中的替換。

這個物件可以透過規格擴展進行擴充。

伺服器物件範例

單個伺服器將描述為

{
  "url": "https://development.gigantic-server.com/v1",
  "description": "Development server"
}

url: https://development.gigantic-server.com/v1
description: Development server

以下顯示如何描述多個伺服器，例如，在 OpenAPI 物件的 servers 中

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server

以下顯示如何將變數用於伺服器組態

{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}

servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
  description: The production API server
  variables:
    username:
      # note! no enum here means it is an open value
      default: demo
      description: this value is assigned by the service provider, in this example `gigantic-server.com`
    port:
      enum:
        - '8443'
        - '443'
      default: '8443'
    basePath:
      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
      default: v2

伺服器變數物件

一個物件，表示用於伺服器 URL 範本替換的伺服器變數。

固定欄位

欄位名稱	類型	描述
enum	[`string`]	如果替換選項來自有限的集合，則要使用的一組字串值枚舉。該陣列不應該為空。
default	`字串`	必要 (REQUIRED)。用於替換的預設值，如果未提供替代值，則應發送該值。請注意，此行為與架構物件對預設值的處理方式不同，因為在這些情況下，參數值是可選的。如果定義了 `enum`，則該值應該存在於枚舉的值中。
description	`字串`	伺服器變數的可選描述。CommonMark 語法可以用於富文本表示。

這個物件可以透過規格擴展進行擴充。

元件物件

保存 OAS 不同方面的可重複使用物件的集合。除非從 components 物件外部的屬性明確參考，否則 components 物件中定義的所有物件都不會對 API 產生任何影響。

固定欄位

欄位名稱	類型	描述
schemas	Map[`string`, 架構物件 \| 參考物件]	一個用於保存可重複使用的架構物件的物件。
responses	Map[`string`, 回應物件 \| 參考物件]	一個用於保存可重複使用的回應物件的物件。
parameters	Map[`string`, 參數物件 \| 參考物件]	一個用於保存可重複使用的參數物件的物件。
examples	Map[`string`, 範例物件 \| 參考物件]	一個用於保存可重複使用的範例物件的物件。
requestBodies	Map[`string`, 請求主體物件 \| 參考物件]	一個用於保存可重複使用的請求主體物件的物件。
headers	Map[`string`, 標頭物件 \| 參考物件]	一個用於保存可重複使用的標頭物件的物件。
securitySchemes	Map[`string`, 安全方案物件 \| 參考物件]	一個用於保存可重複使用的安全方案物件的物件。
links	Map[`string`, 連結物件 \| 參考物件]	一個用於保存可重複使用的連結物件的物件。
callbacks	Map[`string`, 回呼物件 \| 參考物件]	一個用於保存可重複使用的回呼物件的物件。

這個物件可以透過規格擴展進行擴充。

以上聲明的所有固定欄位都是必須使用符合正規表達式：^[a-zA-Z0-9\.\-_]+$ 的鍵的物件。

欄位名稱範例

User
User_1
User_Name
user-name
my.org.User

元件物件範例

"components": {
  "schemas": {
    "GeneralError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  },
  "parameters": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "number of items to skip",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "Entity not found."
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  },
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "http://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "modify pets in your account",
            "read:pets": "read your pets"
          }
        }
      }
    }
  }
}

components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
  parameters:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: max records to return
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.
    GeneralError:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: http://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets

路徑物件

保存單個端點及其操作的相對路徑。路徑會附加到 伺服器物件 中的 URL，以建構完整的 URL。由於 ACL 限制，路徑可以是空的。

模式化欄位

欄位模式	類型	描述
/{path}	路徑項目物件	單個端點的相對路徑。欄位名稱必須以正斜線 (`/`) 開頭。路徑會附加（沒有相對 URL 解析）到來自 `伺服器物件` 的 `url` 欄位的展開 URL，以建構完整的 URL。路徑範本是允許的。在比對 URL 時，具體的（非範本）路徑會在其範本對應物之前比對。具有相同層級結構但具有不同範本名稱的範本路徑必須不存在，因為它們是相同的。在比對不明確的情況下，由工具決定使用哪個。

這個物件可以透過規格擴展進行擴充。

路徑範本比對

假設以下路徑，如果使用，則會先比對具體的定義 /pets/mine

  /pets/{petId}
  /pets/mine

以下路徑被認為是相同且無效的

  /pets/{petId}
  /pets/{name}

以下可能會導致不明確的解析

  /{entity}/me
  /books/{id}

路徑物件範例

{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {         
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}

/pets:
  get:
    description: Returns all pets from the system that the user has access to
    responses:
      '200':
        description: A list of pets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/pet'

路徑項目物件

描述單個路徑上可用的操作。由於 ACL 限制，路徑項目可能是空的。路徑本身仍然會暴露給文件檢視器，但他們不會知道哪些操作和參數可用。

固定欄位

欄位名稱	類型	描述
$ref	`字串`	允許此路徑項目的外部定義。參考的結構必須採用路徑項目物件的格式。如果路徑項目物件欄位同時出現在定義的物件和參考的物件中，則行為是未定義的。
summary	`字串`	一個可選的字串摘要，旨在應用於此路徑中的所有操作。
description	`字串`	一個可選的字串描述，旨在應用於此路徑中的所有操作。CommonMark 語法可以用於富文本表示。
get	操作物件	此路徑上 GET 操作的定義。
put	操作物件	此路徑上 PUT 操作的定義。
post	操作物件	此路徑上 POST 操作的定義。
delete	操作物件	此路徑上 DELETE 操作的定義。
options	操作物件	此路徑上 OPTIONS 操作的定義。
head	操作物件	此路徑上 HEAD 操作的定義。
patch	操作物件	此路徑上 PATCH 操作的定義。
trace	操作物件	此路徑上 TRACE 操作的定義。
servers	[伺服器物件]	用於處理此路徑中所有操作的替代 `server` 陣列。
parameters	[參數物件 \| 參考物件]	適用於此路徑下描述之所有操作的參數列表。這些參數可以在操作層級被覆寫，但不能在此處移除。列表必須不包含重複的參數。唯一的參數由名稱和位置的組合定義。此列表可以使用參考物件來連結至在OpenAPI 物件的 components/parameters 中定義的參數。

這個物件可以透過規格擴展進行擴充。

路徑項目物件範例

{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "responses": {
      "200": {
        "description": "pet response",
        "content": {
          "*/*": {
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        }
      },
      "default": {
        "description": "error payload",
        "content": {
          "text/html": {
            "schema": {
              "$ref": "#/components/schemas/ErrorModel"
            }
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "style": "simple"
    }
  ]
}

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*' :
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        'text/html':
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  schema:
    type: array
    items:
      type: string 
  style: simple

操作物件

描述路徑上的單一 API 操作。

固定欄位

欄位名稱	類型	描述
tags	[`string`]	用於 API 文件控制的標籤列表。標籤可用於依資源或任何其他限定符來邏輯分組操作。
summary	`字串`	對操作內容的簡短摘要。
description	`字串`	對操作行為的詳細解釋。 CommonMark 語法可用於豐富的文字表示。
externalDocs	外部文件物件	此操作的額外外部文件。
operationId	`字串`	用於識別操作的唯一字串。 ID 在 API 中描述的所有操作中必須是唯一的。 operationId 值是區分大小寫的。工具和函式庫可能會使用 operationId 來唯一識別操作，因此建議遵循常見的程式設計命名慣例。
parameters	[參數物件 \| 參考物件]	適用於此操作的參數列表。如果參數已在路徑項目中定義，則新的定義將覆寫它，但永遠無法移除它。列表必須不包含重複的參數。唯一的參數由名稱和位置的組合定義。此列表可以使用參考物件來連結至在OpenAPI 物件的 components/parameters 中定義的參數。
requestBody	請求主體物件 \| 參考物件	適用於此操作的請求主體。僅在 HTTP 方法中支援 `requestBody`，其中 HTTP 1.1 規範RFC7231已明確定義請求主體的語意。在 HTTP 規範模糊不清的其他情況下，消費者應忽略 `requestBody`。
responses	回應物件	必要。執行此操作後傳回的可能回應列表。
callbacks	Map[`string`, 回呼物件 \| 參考物件]	與父操作相關的可能頻外回呼對應表。鍵是回呼物件的唯一識別碼。地圖中的每個值都是一個回呼物件，它描述了可能由 API 提供者起始的請求以及預期的回應。
deprecated	`布林值`	宣告此操作已棄用。消費者應避免使用已宣告的操作。預設值為 `false`。
security	[安全需求物件]	宣告此操作可以使用哪些安全性機制。值列表包含可以使用的替代安全性需求物件。僅需要滿足其中一個安全性需求物件即可授權請求。若要使安全性成為可選，則可以在陣列中包含空的安全性需求 (`{}`)。此定義會覆寫任何已宣告的頂層`security`。若要移除頂層安全性宣告，可以使用空陣列。
servers	[伺服器物件]	用於處理此操作的替代 `server` 陣列。如果在路徑項目物件或根層級指定了替代的 `server` 物件，則它將被此值覆寫。

這個物件可以透過規格擴展進行擴充。

操作物件範例

{
  "tags": [
    "pet"
  ],
  "summary": "Updates a pet in the store with form data",
  "operationId": "updatePetWithForm",
  "parameters": [
    {
      "name": "petId",
      "in": "path",
      "description": "ID of pet that needs to be updated",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "description": "Updated name of the pet",
              "type": "string"
            },
            "status": {
              "description": "Updated status of the pet",
              "type": "string"
            }
          },
          "required": ["status"]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Pet updated.",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    },
    "405": {
      "description": "Method Not Allowed",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    }
  },
  "security": [
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ]
}

tags:
- pet
summary: Updates a pet in the store with form data
operationId: updatePetWithForm
parameters:
- name: petId
  in: path
  description: ID of pet that needs to be updated
  required: true
  schema:
    type: string
requestBody:
  content:
    'application/x-www-form-urlencoded':
      schema:
       properties:
          name:
            description: Updated name of the pet
            type: string
          status:
            description: Updated status of the pet
            type: string
       required:
         - status
responses:
  '200':
    description: Pet updated.
    content:
      'application/json': {}
      'application/xml': {}
  '405':
    description: Method Not Allowed
    content:
      'application/json': {}
      'application/xml': {}
security:
- petstore_auth:
  - write:pets
  - read:pets

外部文件物件

允許引用外部資源以取得擴充文件。

固定欄位

欄位名稱	類型	描述
description	`字串`	目標文件的簡短描述。CommonMark 語法可用於豐富的文字表示。
url	`字串`	必要。目標文件的 URL。值必須為 URL 格式。

這個物件可以透過規格擴展進行擴充。

外部文件物件範例

{
  "description": "Find more info here",
  "url": "https://example.com"
}

description: Find more info here
url: https://example.com

參數物件

描述單一操作參數。

唯一的參數由名稱和位置的組合定義。

參數位置

in 欄位指定了四個可能的參數位置

path - 與路徑範本一起使用，其中參數值實際上是操作 URL 的一部分。這不包含 API 的主機或基本路徑。例如，在 /items/{itemId} 中，路徑參數是 itemId。
query - 附加到 URL 的參數。例如，在 /items?id=### 中，查詢參數是 id。
header - 預期作為請求一部分的自訂標頭。請注意，RFC7230指出標頭名稱不區分大小寫。
cookie - 用於將特定 Cookie 值傳遞給 API。

固定欄位

欄位名稱	類型	描述
name	`字串`	必要。參數的名稱。參數名稱區分大小寫。如果`in`為 `"path"`，則 `name` 欄位必須對應於路徑欄位中發生的範本運算式，位於路徑物件中。請參閱路徑範本以取得更多資訊。如果`in`為 `"header"` 且 `name` 欄位為 `"Accept"`、`"Content-Type"` 或 `"Authorization"`，則應忽略參數定義。對於所有其他情況，`name` 對應於`in`屬性所使用的參數名稱。
in	`字串`	必要。參數的位置。可能的值為 `"query"`、`"header"`、`"path"` 或 `"cookie"`。
description	`字串`	參數的簡短描述。這可能包含使用範例。CommonMark 語法可用於豐富的文字表示。
required	`布林值`	決定此參數是否為必要參數。如果參數位置是 `"path"`，則此屬性為必要且其值必須為 `true`。否則，可以包含該屬性且其預設值為 `false`。
deprecated	`布林值`	指定參數已棄用，且應停止使用。預設值為 `false`。
allowEmptyValue	`布林值`	設定傳遞空值參數的能力。這僅對 `query` 參數有效，並允許傳送具有空值的參數。預設值為 `false`。如果使用了`style`，且行為為 `n/a` (無法序列化)，則應忽略 `allowEmptyValue` 的值。不建議使用此屬性，因為它很可能會在稍後的修訂版中移除。

參數序列化的規則以兩種方式之一指定。對於較簡單的情況，schema 和 style 可以描述參數的結構和語法。

欄位名稱	類型	描述
style	`字串`	描述如何根據參數值的類型來序列化參數值。預設值（基於 `in` 的值）：對於 `query` - `form`；對於 `path` - `simple`；對於 `header` - `simple`；對於 `cookie` - `form`。
explode	`布林值`	當此值為 true 時，類型為 `array` 或 `object` 的參數值會針對陣列的每個值或地圖的每個鍵值組產生個別參數。對於其他類型的參數，此屬性無效。當`style`為 `form` 時，預設值為 `true`。對於所有其他樣式，預設值為 `false`。
allowReserved	`布林值`	決定參數值是否應允許保留字元，如 RFC3986 所定義 `:/?#[]@!$&'()*+,;=`，而不需進行百分比編碼。此屬性僅適用於 `in` 值為 `query` 的參數。預設值為 `false`。
schema	結構描述物件 \| 參考物件	定義用於參數類型的結構描述。
example	任何	參數潛在值的範例。如果存在，則範例應符合指定的結構描述和編碼屬性。 `example` 欄位與 `examples` 欄位互斥。此外，如果參考包含範例的 `schema`，則 `example` 值應覆寫結構描述提供的範例。為了表示無法在 JSON 或 YAML 中自然表示的媒體類型範例，字串值可以包含必要的逸出範例。
examples	Map[ `string`, 範例物件 \| 參考物件]	參數潛在值的範例。每個範例應包含以參數編碼中指定的正確格式的值。 `examples` 欄位與 `example` 欄位互斥。此外，如果參考包含範例的 `schema`，則 `examples` 值應覆寫結構描述提供的範例。

對於更複雜的情況，content 屬性可以定義參數的媒體類型和結構描述。參數必須包含 schema 屬性或 content 屬性，但不能同時包含兩者。當與 schema 物件一起提供 example 或 examples 時，範例必須遵循參數的規定序列化策略。

欄位名稱	類型	描述
content	Map[`string`, 媒體類型物件]	包含參數表示的對應表。鍵是媒體類型，而值描述了它。對應表必須僅包含一個項目。

樣式值

為了支援序列化簡單參數的常見方式，定義了一組 style 值。

`樣式`	`類型`	`於`	註解
矩陣中	`基本型別`、`陣列`、`物件`	`路徑`	由 RFC6570 定義的路徑樣式參數
標籤	`基本型別`、`陣列`、`物件`	`路徑`	由 RFC6570 定義的標籤樣式參數
表單	`基本型別`、`陣列`、`物件`	`查詢`、`Cookie`	由 RFC6570 定義的表單樣式參數。此選項使用 OpenAPI 2.0 的 `csv` (當 `explode` 為 false 時) 或 `multi` (當 `explode` 為 true 時) 值取代 `collectionFormat`。
簡單	`陣列`	`路徑`、`標頭`	由 RFC6570 定義的簡單樣式參數。此選項使用 OpenAPI 2.0 的 `csv` 值取代 `collectionFormat`。
空格分隔	`陣列`	`查詢`	以空格分隔的陣列值。此選項取代 OpenAPI 2.0 中等於 `ssv` 的 `collectionFormat`。
管道分隔	`陣列`	`查詢`	以管道分隔的陣列值。此選項取代 OpenAPI 2.0 中等於 `pipes` 的 `collectionFormat`。
深層物件	`物件`	`查詢`	提供使用表單參數呈現巢狀物件的簡單方式。

樣式範例

假設一個名為 color 的參數具有以下其中一個值

   string -> "blue"
   array -> ["blue","black","brown"]
   object -> { "R": 100, "G": 200, "B": 150 }

下表顯示每個值的呈現差異範例。

`樣式`	`展開`	`空`	`字串`	`陣列`	`物件`
矩陣中	false	;color	;color=blue	;color=blue,black,brown	;color=R,100,G,200,B,150
矩陣中	true	;color	;color=blue	;color=blue;color=black;color=brown	;R=100;G=200;B=150
標籤	false	.	.blue	.blue.black.brown	.R.100.G.200.B.150
標籤	true	.	.blue	.blue.black.brown	.R=100.G=200.B=150
表單	false	color=	color=blue	color=blue,black,brown	color=R,100,G,200,B,150
表單	true	color=	color=blue	color=blue&color=black&color=brown	R=100&G=200&B=150
簡單	false	不適用	blue	blue,black,brown	R,100,G,200,B,150
簡單	true	不適用	blue	blue,black,brown	R=100,G=200,B=150
空格分隔	false	不適用	不適用	blue%20black%20brown	R%20100%20G%20200%20B%20150
管道分隔	false	不適用	不適用	blue\|black\|brown	R\|100\|G\|200\|B\|150
深層物件	true	不適用	不適用	不適用	color[R]=100&color[G]=200&color[B]=150

這個物件可以透過規格擴展進行擴充。

參數物件範例

一個帶有 64 位元整數陣列的標頭參數

{
  "name": "token",
  "in": "header",
  "description": "token to be passed as a header",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "integer",
      "format": "int64"
    }
  },
  "style": "simple"
}

name: token
in: header
description: token to be passed as a header
required: true
schema:
  type: array
  items:
    type: integer
    format: int64
style: simple

一個字串值的路徑參數

{
  "name": "username",
  "in": "path",
  "description": "username to fetch",
  "required": true,
  "schema": {
    "type": "string"
  }
}

name: username
in: path
description: username to fetch
required: true
schema:
  type: string

一個字串值的可選查詢參數，允許透過重複查詢參數來使用多個值

{
  "name": "id",
  "in": "query",
  "description": "ID of the object to fetch",
  "required": false,
  "schema": {
    "type": "array",
    "items": {
      "type": "string"
    }
  },
  "style": "form",
  "explode": true
}

name: id
in: query
description: ID of the object to fetch
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true

一個自由形式的查詢參數，允許特定類型的未定義參數

{
  "in": "query",
  "name": "freeForm",
  "schema": {
    "type": "object",
    "additionalProperties": {
      "type": "integer"
    },
  },
  "style": "form"
}

in: query
name: freeForm
schema:
  type: object
  additionalProperties:
    type: integer
style: form

一個使用 content 定義序列化的複雜參數

{
  "in": "query",
  "name": "coordinates",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "lat",
          "long"
        ],
        "properties": {
          "lat": {
            "type": "number"
          },
          "long": {
            "type": "number"
          }
        }
      }
    }
  }
}

in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number

請求主體物件

描述單一請求主體。

固定欄位

欄位名稱	類型	描述
描述	`字串`	請求主體的簡要描述。這可以包含使用範例。CommonMark 語法可用於豐富文本表示。
內容	Map[`string`, 媒體類型物件]	必要。請求主體的內容。鍵是媒體類型或媒體類型範圍，值描述它。對於符合多個鍵的請求，僅適用最特定的鍵。例如，text/plain 會覆寫 text/*
必要	`布林值`	確定請求主體在請求中是否為必要。預設值為 `false`。

這個物件可以透過規格擴展進行擴充。

請求主體範例

具有參照模型定義的請求主體。

{
  "description": "user to add to the system",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User Example",
            "externalValue": "http://foo.bar/examples/user-example.json"
          }
        }
    },
    "application/xml": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User example in XML",
            "externalValue": "http://foo.bar/examples/user-example.xml"
          }
        }
    },
    "text/plain": {
      "examples": {
        "user" : {
            "summary": "User example in Plain text",
            "externalValue": "http://foo.bar/examples/user-example.txt"
        }
      }
    },
    "*/*": {
      "examples": {
        "user" : {
            "summary": "User example in other format",
            "externalValue": "http://foo.bar/examples/user-example.whatever"
        }
      }
    }
  }
}

description: user to add to the system
content:
  'application/json':
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User Example
        externalValue: 'http://foo.bar/examples/user-example.json'
  'application/xml':
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User Example in XML
        externalValue: 'http://foo.bar/examples/user-example.xml'
  'text/plain':
    examples:
      user:
        summary: User example in text plain format
        externalValue: 'http://foo.bar/examples/user-example.txt'
  '*/*':
    examples:
      user:
        summary: User example in other format
        externalValue: 'http://foo.bar/examples/user-example.whatever'

一個字串值陣列的本體參數

{
  "description": "user to add to the system",
  "content": {
    "text/plain": {
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

description: user to add to the system
required: true
content:
  text/plain:
    schema:
      type: array
      items:
        type: string

媒體類型物件

每個媒體類型物件都提供其鍵所識別的媒體類型的綱要和範例。

固定欄位

欄位名稱	類型	描述
綱要	結構描述物件 \| 參考物件	定義請求、回應或參數內容的綱要。
範例	任何	媒體類型的範例。範例物件的格式應與媒體類型指定的格式相同。`example` 欄位與 `examples` 欄位互斥。此外，如果參照包含範例的 `schema`，則 `example` 值應覆寫綱要提供的範例。
範例	Map[ `string`, 範例物件 \| 參考物件]	媒體類型的範例。如果存在，每個範例物件都應符合媒體類型和指定的綱要。`examples` 欄位與 `example` 欄位互斥。此外，如果參照包含範例的 `schema`，則 `examples` 值應覆寫綱要提供的範例。
編碼	Map[`字串`, 編碼物件]	屬性名稱及其編碼資訊之間的對應。鍵（屬性名稱）必須以屬性的形式存在於綱要中。當媒體類型為 `multipart` 或 `application/x-www-form-urlencoded` 時，編碼物件應僅適用於 `requestBody` 物件。

這個物件可以透過規格擴展進行擴充。

媒體類型範例

{
  "application/json": {
    "schema": {
         "$ref": "#/components/schemas/Pet"
    },
    "examples": {
      "cat" : {
        "summary": "An example of a cat",
        "value":
          {
            "name": "Fluffy",
            "petType": "Cat",
            "color": "White",
            "gender": "male",
            "breed": "Persian"
          }
      },
      "dog": {
        "summary": "An example of a dog with a cat's name",
        "value" :  {
          "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        },
      "frog": {
          "$ref": "#/components/examples/frog-example"
        }
      }
    }
  }
}

application/json:
  schema:
    $ref: "#/components/schemas/Pet"
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: "#/components/examples/frog-example"

檔案上傳的考量事項

與 2.0 規格相比，OpenAPI 中的 file 輸入/輸出內容與任何其他綱要類型使用相同的語義來描述。具體而言

# content transferred with base64 encoding
schema:
  type: string
  format: base64

# content transferred in binary (octet-stream):
schema:
  type: string
  format: binary

這些範例適用於檔案上傳的輸入酬載或回應酬載。

用於在 POST 操作中提交檔案的 requestBody 可能如下例所示

requestBody:
  content:
    application/octet-stream:
      schema:
        # a binary file of any type
        type: string
        format: binary

此外，可以指定特定的媒體類型

# multiple, specific media types may be specified:
requestBody:
  content:
      # a binary file of type png or jpeg
    'image/jpeg':
      schema:
        type: string
        format: binary
    'image/png':
      schema:
        type: string
        format: binary

若要上傳多個檔案，則必須使用 multipart 媒體類型

requestBody:
  content:
    multipart/form-data:
      schema:
        properties:
          # The property name 'file' will be used for all files.
          file:
            type: array
            items:
              type: string
              format: binary

支援 x-www-form-urlencoded 請求主體

若要透過 RFC1866 使用表單 URL 編碼提交內容，可以使用以下定義

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # complex types are stringified to support RFC 1866
            type: object
            properties: {}

在此範例中，傳遞至伺服器時，requestBody 中的內容必須按照 RFC1866 進行字串化。此外，address 欄位的複雜物件也將進行字串化。

在 application/x-www-form-urlencoded 內容類型中傳遞複雜物件時，此類屬性的預設序列化策略在 編碼物件 的 style 屬性中描述為 form。

`multipart` 內容的特殊考量事項

當將請求主體傳輸到操作時，通常會使用 multipart/form-data 作為 Content-Type。與 2.0 不同的是，使用 multipart 內容時，必須使用 schema 來定義操作的輸入參數。這支援複雜的結構，並支援多檔案上傳的機制。

在傳遞 multipart 類型時，可以使用邊界來分隔傳輸內容的區段 — 因此，為 multipart 定義了以下預設 Content-Type

如果屬性是基本型別，或基本值的陣列，則預設 Content-Type 為 text/plain
如果屬性是複雜的，或複雜值的陣列，則預設 Content-Type 為 application/json
如果屬性是具有 format: binary 或 format: base64 的 type: string (也就是檔案物件)，則預設 Content-Type 為 application/octet-stream

範例

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # default Content-Type for objects is `application/json`
            type: object
            properties: {}
          profileImage:
            # default Content-Type for string/binary is `application/octet-stream`
            type: string
            format: binary
          children:
            # default Content-Type for arrays is based on the `inner` type (text/plain here)
            type: array
            items:
              type: string
          addresses:
            # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example)
            type: array
            items:
              type: '#/components/schemas/Address'

引入 encoding 屬性可讓您控制 multipart 請求主體部分的序列化。此屬性僅適用於 multipart 和 application/x-www-form-urlencoded 請求主體。

編碼物件

套用至單一綱要屬性的單一編碼定義。

固定欄位

欄位名稱	類型	描述
contentType	`字串`	用於編碼特定屬性的 Content-Type。預設值取決於屬性類型：對於 `format` 為 `binary` 的 `string` – `application/octet-stream`；對於其他基本類型 – `text/plain`；對於 `object` - `application/json`；對於 `array` – 預設值是根據內部類型定義的。該值可以是特定的媒體類型 (例如 `application/json`)、萬用字元媒體類型 (例如 `image/*`)，或是這兩種以逗號分隔的清單。
標頭	Map[`string`, 標頭物件 \| 參考物件]	允許將其他資訊作為標頭提供的對應，例如 `Content-Disposition`。`Content-Type` 是單獨描述的，應在此部分中忽略。如果請求主體媒體類型不是 `multipart`，則應忽略此屬性。
樣式	`字串`	描述特定屬性值將如何根據其類型進行序列化。請參閱參數物件以取得 `style` 屬性的詳細資訊。行為遵循與 `query` 參數相同的值，包括預設值。如果請求主體媒體類型不是 `application/x-www-form-urlencoded`，則應忽略此屬性。
展開	`布林值`	當此值為 true 時，類型為 `array` 或 `object` 的屬性值會為陣列的每個值或地圖的鍵值對產生單獨的參數。對於其他類型的屬性，此屬性無效。當 `style` 為 `form` 時，預設值為 `true`。對於所有其他樣式，預設值為 `false`。如果請求主體媒體類型不是 `application/x-www-form-urlencoded`，則應忽略此屬性。
允許保留	`布林值`	決定參數值是否應允許保留字元 (由 RFC3986 定義) `:/?#[]@!$&'()*+,;=` 不經過百分比編碼就包含在內。預設值為 `false`。如果請求主體媒體類型不是 `application/x-www-form-urlencoded`，則應忽略此屬性。

這個物件可以透過規格擴展進行擴充。

編碼物件範例

requestBody:
  content:
    multipart/mixed:
      schema:
        type: object
        properties:
          id:
            # default is text/plain
            type: string
            format: uuid
          address:
            # default is application/json
            type: object
            properties: {}
          historyMetadata:
            # need to declare XML format!
            description: metadata in XML format
            type: object
            properties: {}
          profileImage:
            # default is application/octet-stream, need to declare an image type only!
            type: string
            format: binary
      encoding:
        historyMetadata:
          # require XML Content-Type in utf-8 encoding
          contentType: application/xml; charset=utf-8
        profileImage:
          # only accept png/jpeg
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

回應物件

操作預期回應的容器。容器將 HTTP 回應程式碼對應到預期的回應。

不一定預期文件涵蓋所有可能的 HTTP 回應程式碼，因為它們可能是事先未知的。但是，預期文件會涵蓋成功操作回應和任何已知的錯誤。

default 可用作所有規格中未個別涵蓋的 HTTP 程式碼的預設回應物件。

回應物件 必須包含至少一個回應程式碼，且應為成功操作呼叫的回應。

固定欄位

欄位名稱	類型	描述
預設	回應物件 \| 參考物件	對特定 HTTP 回應程式碼宣告以外的回應文件。使用此欄位來涵蓋未宣告的回應。參考物件可以連結到 OpenAPI 物件的 components/responses 區段定義的回應。

模式化欄位

欄位模式	類型	描述
HTTP 狀態碼	回應物件 \| 參考物件	任何 HTTP 狀態碼都可用作屬性名稱，但每個程式碼僅有一個屬性，以描述該 HTTP 狀態碼的預期回應。參考物件可以連結到 OpenAPI 物件的 components/responses 區段中定義的回應。此欄位必須以引號括起來 (例如 "200")，才能在 JSON 和 YAML 之間相容。若要定義一系列的回應程式碼，此欄位可以包含大寫萬用字元 `X`。例如，`2XX` 代表 `[200-299]` 之間的所有回應程式碼。僅允許下列範圍定義：`1XX`、`2XX`、`3XX`、`4XX` 和 `5XX`。如果使用明確的程式碼定義回應，則明確的程式碼定義會優先於該程式碼的範圍定義。

這個物件可以透過規格擴展進行擴充。

回應物件範例

針對成功操作的回應 200 以及其他回應的預設回應 (表示錯誤)

{
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}

'200':
  description: a pet to be returned
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'
default:
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorModel'

回應物件

描述來自 API 操作的單一回應，包括設計階段，根據回應建立操作的靜態 links。

固定欄位

欄位名稱	類型	描述
描述	`字串`	必要。簡短描述回應。CommonMark 語法可用於富文本表示。
headers	Map[`string`, 標頭物件 \| 參考物件]	將標頭名稱映射到其定義。RFC7230 說明標頭名稱不區分大小寫。如果回應標頭定義的名稱為 `"Content-Type"`，則應忽略它。
content	Map[`string`, 媒體類型物件]	包含潛在回應酬載描述的映射。鍵值是媒體類型或媒體類型範圍，值描述它。對於匹配多個鍵值的回應，僅適用最特定的鍵值。例如 text/plain 會覆寫 text/*。
links	Map[`string`, 連結物件 \| 參考物件]	可以從回應追蹤的操作連結映射。映射的鍵值是連結的簡短名稱，遵循元件物件名稱的命名約束。

這個物件可以透過規格擴展進行擴充。

回應物件範例

複雜類型陣列的回應

{
  "description": "A complex object array response",
  "content": {
    "application/json": {
      "schema": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/VeryComplexType"
        }
      }
    }
  }
}

description: A complex object array response
content:
  application/json:
    schema:
      type: array
      items:
        $ref: '#/components/schemas/VeryComplexType'

具有字串類型的回應

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      }
    }
  }

}

description: A simple string response
content:
  text/plain:
    schema:
      type: string

具有標頭的純文字回應

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string",
        "example": "whoa!"
      }
    }
  },
  "headers": {
    "X-Rate-Limit-Limit": {
      "description": "The number of allowed requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Remaining": {
      "description": "The number of remaining requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Reset": {
      "description": "The number of seconds left in the current period",
      "schema": {
        "type": "integer"
      }
    }
  }
}

description: A simple string response
content:
  text/plain:
    schema:
      type: string
    example: 'whoa!'
headers:
  X-Rate-Limit-Limit:
    description: The number of allowed requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Remaining:
    description: The number of remaining requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Reset:
    description: The number of seconds left in the current period
    schema:
      type: integer

沒有傳回值的回應

{
  "description": "object created"
}

description: object created

回呼物件

與父操作相關的可能帶外回呼映射。映射中的每個值都是一個路徑項目物件，描述 API 提供者可能啟動的一組請求和預期的回應。用於識別路徑項目物件的鍵值是一個表達式，在執行時求值，以識別用於回呼操作的 URL。

模式化欄位

欄位模式	類型	描述
{表達式}	路徑項目物件	用於定義回呼請求和預期回應的路徑項目物件。有一個完整範例可用。

這個物件可以透過規格擴展進行擴充。

鍵值表達式

用於識別路徑項目物件的鍵值是一個執行時表達式，可以在執行時 HTTP 請求/回應的上下文中求值，以識別用於回呼請求的 URL。一個簡單的範例可能是 $request.body#/url。然而，使用執行時表達式可以存取完整的 HTTP 訊息。這包括存取 JSON Pointer RFC6901 可以引用的主體任何部分。

例如，給定以下 HTTP 請求

POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 187

{
  "failedUrl" : "http://clientdomain.com/failed",
  "successUrls" : [
    "http://clientdomain.com/fast",
    "http://clientdomain.com/medium",
    "http://clientdomain.com/slow"
  ]
}

201 Created
Location: http://example.org/subscription/1

以下範例展示了各種表達式如何求值，假設回呼操作具有名為 eventType 的路徑參數和名為 queryUrl 的查詢參數。

表達式	值
$url	http://example.org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning
$method	POST
$request.path.eventType	myevent
$request.query.queryUrl	http://clientdomain.com/stillrunning
$request.header.content-Type	application/json
$request.body#/failedUrl	http://clientdomain.com/failed
$request.body#/successUrls/2	http://clientdomain.com/medium
$response.header.Location	http://example.org/subscription/1

回呼物件範例

以下範例使用使用者提供的 queryUrl 查詢字串參數來定義回呼 URL。這是一個如何使用回呼物件來描述 WebHook 回呼的範例，該回呼與訂閱操作一起使用，以啟用註冊 WebHook。

myCallback:
  '{$request.query.queryUrl}':
    post:
      requestBody:
        description: Callback payload
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

以下範例顯示了一個回呼，其中伺服器是硬編碼的，但是查詢字串參數是從請求主體中的 id 和 email 屬性填充的。

transactionCallback:
  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
    post:
      requestBody:
        description: Callback payload
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

範例物件

固定欄位

欄位名稱	類型	描述
summary	`字串`	範例的簡短描述。
description	`字串`	範例的詳細描述。CommonMark 語法可用於富文本表示。
value	任何	嵌入的文字範例。`value` 欄位和 `externalValue` 欄位是互斥的。要表示無法自然地在 JSON 或 YAML 中表示的媒體類型範例，請使用字串值來包含範例，並在必要時進行跳脫。
externalValue	`字串`	指向文字範例的 URL。這提供了參考無法輕易包含在 JSON 或 YAML 文件中的範例的功能。`value` 欄位和 `externalValue` 欄位是互斥的。

這個物件可以透過規格擴展進行擴充。

在所有情況下，範例值都應與其關聯值的類型綱要相容。工具實作可能會選擇自動驗證相容性，並在不相容時拒絕範例值。

範例物件範例

在請求主體中

requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value: {"foo": "bar"}
        bar:
          summary: A bar example
          value: {"bar": "baz"}
    'application/xml':
      examples:
        xmlExample:
          summary: This is an example in XML
          externalValue: 'http://example.org/examples/address-example.xml'
    'text/plain':
      examples:
        textExample:
          summary: This is a text example
          externalValue: 'http://foo.bar/examples/address-example.txt'

在參數中

parameters:
  - name: 'zipCode'
    in: 'query'
    schema:
      type: 'string'
      format: 'zip-code'
    examples:
      zip-example:
        $ref: '#/components/examples/zip-example'

在回應中

responses:
  '200':
    description: your car appointment has been booked
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/SuccessResponse'
        examples:
          confirmation-success:
            $ref: '#/components/examples/confirmation-success'

連結物件

連結物件表示回應的可能設計時連結。連結的存在並不能保證呼叫者成功呼叫它的能力，而是提供回應和其他操作之間已知的關係和遍歷機制。

與動態連結（即在回應酬載中提供的連結）不同，OAS 連結機制不需要執行時回應中的連結資訊。

為了計算連結並提供執行它們的指示，執行時表達式用於存取操作中的值，並在呼叫連結操作時將其用作參數。

固定欄位

欄位名稱	類型	描述
operationRef	`字串`	OAS 操作的相對或絕對 URI 參考。此欄位與 `operationId` 欄位互斥，並且必須指向操作物件。相對 `operationRef` 值可用於在 OpenAPI 定義中尋找現有的操作物件。
operationId	`字串`	現有、可解析的 OAS 操作的名稱，使用唯一的 `operationId` 定義。此欄位與 `operationRef` 欄位互斥。
parameters	Map[`string`, Any \| {表達式}]	一個映射，表示要傳遞給使用 `operationId` 指定或透過 `operationRef` 識別的操作的參數。鍵值是要使用的參數名稱，而值可以是常數或要評估並傳遞給連結操作的表達式。可以使用參數位置 `[{in}.]{name}` 來限定參數名稱，以用於在不同位置使用相同參數名稱的操作（例如 path.id）。
requestBody	Any \| {表達式}	在呼叫目標操作時用作請求主體的文字值或 {表達式}。
description	`字串`	連結的描述。CommonMark 語法可用於富文本表示。
server	伺服器物件	目標操作要使用的伺服器物件。

這個物件可以透過規格擴展進行擴充。

連結操作必須使用 operationRef 或 operationId 識別。在 operationId 的情況下，它必須是唯一的並在 OAS 文件的範圍內解析。由於存在名稱衝突的可能性，對於具有外部參考的規格，首選 operationRef 語法。

範例

計算請求操作的連結，其中 $request.path.id 用於將請求參數傳遞給連結操作。

paths:
  /users/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    get:
      responses:
        '200':
          description: the user being returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid: # the unique user id
                    type: string
                    format: uuid
          links:
            address:
              # the target link operationId
              operationId: getUserAddress
              parameters:
                # get the `id` field from the request path parameter named `id`
                userId: $request.path.id
  # the path item of the linked operation
  /users/{userid}/address:
    parameters:
    - name: userid
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    # linked operation
    get:
      operationId: getUserAddress
      responses:
        '200':
          description: the user's address

當執行時表達式求值失敗時，不會將參數值傳遞給目標操作。

回應主體中的值可以用於驅動連結操作。

links:
  address:
    operationId: getUserAddressByUUID
    parameters:
      # get the `uuid` field from the `uuid` field in the response body
      userUuid: $response.body#/uuid

用戶端自行決定是否追蹤所有連結。僅僅因為存在關係，並不能保證權限或成功呼叫該連結的能力。

OperationRef 範例

由於參考 operationId 可能不可行（operationId 是操作物件中的可選欄位），因此也可能透過相對 operationRef 進行參考

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

或絕對 operationRef

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

請注意，在使用 operationRef 時，在使用 JSON 參考時，必須使用跳脫斜線。

執行時表達式

執行時表達式允許根據實際 API 呼叫中 HTTP 訊息中才可用的資訊來定義值。此機制由連結物件和回呼物件使用。

執行時表達式由以下 ABNF 語法定義

      expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
      source = ( header-reference / query-reference / path-reference / body-reference )
      header-reference = "header." token
      query-reference = "query." name 
      path-reference = "path." name
      body-reference = "body" ["#" json-pointer ]
      json-pointer    = *( "/" reference-token )
      reference-token = *( unescaped / escaped )
      unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
         ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
      escaped         = "~" ( "0" / "1" )
        ; representing '~' and '/', respectively
      name = *( CHAR )
      token = 1*tchar
      tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
        "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA

在這裡，json-pointer 取自 RFC 6901，char 取自 RFC 7159，而 token 取自 RFC 7230。

name 識別符號區分大小寫，而 token 不區分大小寫。

下表提供了執行時表達式的範例以及它們在值中的用法範例

範例

來源位置	範例表達式	注意事項
HTTP 方法	`$method`	`$method` 的允許值將是 HTTP 操作的允許值。
請求的媒體類型	`$request.header.accept`
請求參數	`$request.path.id`	請求參數必須在父操作的 `parameters` 區段中宣告，否則無法評估。這包括請求標頭。
請求主體屬性	`$request.body#/user/uuid`	在接受酬載的操作中，可以參考 `requestBody` 的部分或整個主體。
請求 URL	`$url`
回應值	`$response.body#/status`	在傳回酬載的操作中，可以參考回應主體的部分或整個主體。
回應標頭	`$response.header.Server`	只有單個標頭值可用

執行時表達式保留所參考值的類型。可以透過將表達式括在 {} 大括號中，將表達式嵌入字串值中。

標頭物件

標頭物件遵循參數物件的結構，但有以下變更

name 不得指定，它在對應的 headers 映射中給出。
in 不得指定，它隱含在 header 中。
受位置影響的所有特徵都必須適用於 header 的位置（例如，style）。

標頭物件範例

integer 類型的簡單標頭

{
  "description": "The number of allowed requests in the current period",
  "schema": {
    "type": "integer"
  }
}

description: The number of allowed requests in the current period
schema:
  type: integer

標籤物件

將中繼資料新增到操作物件使用的單個標籤。在操作物件實例中定義的每個標籤不一定都需要一個標籤物件。

固定欄位

欄位名稱	類型	描述
name	`字串`	必要。標籤的名稱。
描述	`字串`	標籤的簡短描述。可以使用 CommonMark 語法來呈現富文本格式。
externalDocs	外部文件物件	此標籤的額外外部文件。

這個物件可以透過規格擴展進行擴充。

標籤物件範例

{
	"name": "pet",
	"description": "Pets operations"
}

name: pet
description: Pets operations

參照物件

一個簡單的物件，允許參考規格中內部和外部的其他元件。

參考物件由 JSON Reference 定義，並遵循相同的結構、行為和規則。

對於此規格，參考解析是按照 JSON Reference 規格的定義完成的，而不是按照 JSON Schema 規格完成的。

固定欄位

欄位名稱	類型	描述
$ref	`字串`	必要。參考字串。

此物件不能使用額外的屬性進行擴展，任何添加的屬性都應被忽略。

參考物件範例

{
	"$ref": "#/components/schemas/Pet"
}

$ref: '#/components/schemas/Pet'

相對 Schema 文件範例

{
  "$ref": "Pet.json"
}

$ref: Pet.yaml

帶有嵌入式 Schema 的相對文件範例

{
  "$ref": "definitions.json#/Pet"
}

$ref: definitions.yaml#/Pet

結構描述物件

Schema 物件允許定義輸入和輸出資料類型。這些類型可以是物件，也可以是基本類型和陣列。此物件是 JSON Schema 規格 Wright Draft 00 的擴展子集。

有關屬性的更多資訊，請參閱 JSON Schema Core 和 JSON Schema Validation。除非另有說明，否則屬性定義遵循 JSON Schema。

屬性

以下屬性直接取自 JSON Schema 定義，並遵循相同的規範

title
multipleOf
maximum
exclusiveMaximum
minimum
exclusiveMinimum
maxLength
minLength
pattern（此字串應為有效的正規表示式，根據 Ecma-262 Edition 5.1 正規表示式方言）
maxItems
minItems
uniqueItems
maxProperties
minProperties
required
enum

以下屬性取自 JSON Schema 定義，但其定義已調整為 OpenAPI 規格。

type - 值必須為字串。不支援透過陣列的多種類型。
allOf - 行內或參考的 schema 必須是 Schema 物件，而不是標準的 JSON Schema。
oneOf - 行內或參考的 schema 必須是 Schema 物件，而不是標準的 JSON Schema。
anyOf - 行內或參考的 schema 必須是 Schema 物件，而不是標準的 JSON Schema。
not - 行內或參考的 schema 必須是 Schema 物件，而不是標準的 JSON Schema。
items - 值必須是物件，而不是陣列。行內或參考的 schema 必須是 Schema 物件，而不是標準的 JSON Schema。如果 type 是 array，則必須存在 items。
properties - 屬性定義必須是 Schema 物件，而不是標準的 JSON Schema（行內或參考）。
additionalProperties - 值可以是布林值或物件。行內或參考的 schema 必須是 Schema 物件，而不是標準的 JSON Schema。與 JSON Schema 一致，additionalProperties 預設為 true。
description - 可以使用 CommonMark 語法來呈現富文本格式。
format - 有關更多詳細資訊，請參閱資料類型格式。在依賴 JSON Schema 定義的格式的同時，OAS 提供了一些額外的預定義格式。
default - 預設值表示如果未提供 schema 的值，則輸入的使用者將假定的值。與 JSON Schema 不同，該值必須符合在同一級別定義的 Schema 物件的已定義類型。例如，如果 type 是 string，則 default 可以是 "foo"，但不能是 1。

或者，任何可以使用 Schema 物件的地方，都可以使用參考物件來代替。這允許參考定義，而不是行內定義它們。

JSON Schema 規格中定義但在此處未提及的其他屬性嚴格不支援。

除了 JSON Schema 子集欄位外，以下欄位可用於進一步的 schema 文件

固定欄位

欄位名稱	類型	描述
nullable	`布林值`	`true` 值將 `"null"` 新增至 `type` 關鍵字指定的允許類型，僅當 `type` 在同一 Schema 物件中明確定義時。其他 Schema 物件約束保留其定義的行為，因此可能不允許使用 `null` 作為值。`false` 值會使指定的或預設的 `type` 保持不變。預設值為 `false`。
discriminator	辨別器物件	新增對多型性的支援。辨別器是一個物件名稱，用於區分可能滿足 payload 描述的其他 schema。有關更多詳細資訊，請參閱組合和繼承。
readOnly	`布林值`	僅適用於 Schema `"properties"` 定義。將屬性宣告為「唯讀」。這表示它可以作為回應的一部分發送，但不應作為請求的一部分發送。如果屬性被標記為 `readOnly` 為 `true` 並且在 `required` 清單中，則 `required` 僅在回應中生效。屬性不能同時被標記為 `readOnly` 和 `writeOnly` 為 `true`。預設值為 `false`。
writeOnly	`布林值`	僅適用於 Schema `"properties"` 定義。將屬性宣告為「僅寫入」。因此，它可以作為請求的一部分發送，但不應作為回應的一部分發送。如果屬性被標記為 `writeOnly` 為 `true` 並且在 `required` 清單中，則 `required` 僅在請求中生效。屬性不能同時被標記為 `readOnly` 和 `writeOnly` 為 `true`。預設值為 `false`。
xml	XML 物件	此欄位僅可用於屬性 schema。它對根 schema 沒有影響。新增額外的中繼資料，以描述此屬性的 XML 表示。
externalDocs	外部文件物件	此 schema 的額外外部文件。
example	任何	一個自由格式的屬性，用於包含此 schema 實例的範例。為了表示無法在 JSON 或 YAML 中自然表示的範例，可以使用字串值來包含範例，並在必要時進行跳脫字元處理。
deprecated	`布林值`	指定 schema 已過時，應停止使用。預設值為 `false`。

這個物件可以透過規格擴展進行擴充。

組合和繼承（多型性）

OpenAPI 規格允許使用 JSON Schema 的 allOf 屬性組合和擴展模型定義，實際上提供了模型組合。allOf 接受物件定義的陣列，這些定義會獨立驗證，但共同組成單一物件。

雖然組合提供了模型的可擴展性，但它並不意味著模型之間存在階層關係。為了支援多型性，OpenAPI 規格新增了 discriminator 欄位。使用時，discriminator 將是屬性的名稱，該屬性決定哪個 schema 定義驗證模型的結構。因此，discriminator 欄位必須是必要欄位。有兩種方法可以為繼承實例定義辨別器的值。

使用 schema 名稱。
透過以新值覆蓋屬性來覆蓋 schema 名稱。如果存在新值，則此值優先於 schema 名稱。因此，在多型性中不能使用沒有給定 ID 的行內 schema 定義。

XML 建模

當將 JSON 定義轉換為 XML 時，xml 屬性允許額外的定義。XML 物件包含有關可用選項的更多資訊。

Schema 物件範例

基本類型範例

{
  "type": "string",
  "format": "email"
}

type: string
format: email

簡單模型

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "address": {
      "$ref": "#/components/schemas/Address"
    },
    "age": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
    }
  }
}

type: object
required:
- name
properties:
  name:
    type: string
  address:
    $ref: '#/components/schemas/Address'
  age:
    type: integer
    format: int32
    minimum: 0

具有 Map/Dictionary 屬性的模型

對於簡單的字串到字串對應

{
  "type": "object",
  "additionalProperties": {
    "type": "string"
  }
}

type: object
additionalProperties:
  type: string

對於字串到模型對應

{
  "type": "object",
  "additionalProperties": {
    "$ref": "#/components/schemas/ComplexModel"
  }
}

type: object
additionalProperties:
  $ref: '#/components/schemas/ComplexModel'

帶有範例的模型

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "example": {
    "name": "Puma",
    "id": 1
  }
}

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
required:
- name
example:
  name: Puma
  id: 1

具有組合的模型

{
  "components": {
    "schemas": {
      "ErrorModel": {
        "type": "object",
        "required": [
          "message",
          "code"
        ],
        "properties": {
          "message": {
            "type": "string"
          },
          "code": {
            "type": "integer",
            "minimum": 100,
            "maximum": 600
          }
        }
      },
      "ExtendedErrorModel": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorModel"
          },
          {
            "type": "object",
            "required": [
              "rootCause"
            ],
            "properties": {
              "rootCause": {
                "type": "string"
              }
            }
          }
        ]
      }
    }
  }
}

components:
  schemas:
    ErrorModel:
      type: object
      required:
      - message
      - code
      properties:
        message:
          type: string
        code:
          type: integer
          minimum: 100
          maximum: 600
    ExtendedErrorModel:
      allOf:
      - $ref: '#/components/schemas/ErrorModel'
      - type: object
        required:
        - rootCause
        properties:
          rootCause:
            type: string

具有多型性支援的模型

{
  "components": {
    "schemas": {
      "Pet": {
        "type": "object",
        "discriminator": {
          "propertyName": "petType"
        },
        "properties": {
          "name": {
            "type": "string"
          },
          "petType": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "petType"
        ]
      },
      "Cat": {
        "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "huntingSkill": {
                "type": "string",
                "description": "The measured skill for hunting",
                "default": "lazy",
                "enum": [
                  "clueless",
                  "lazy",
                  "adventurous",
                  "aggressive"
                ]
              }
            },
            "required": [
              "huntingSkill"
            ]
          }
        ]
      },
      "Dog": {
        "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "packSize": {
                "type": "integer",
                "format": "int32",
                "description": "the size of the pack the dog is from",
                "default": 0,
                "minimum": 0
              }
            },
            "required": [
              "packSize"
            ]
          }
        ]
      }
    }
  }
}

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
      properties:
        name:
          type: string
        petType:
          type: string
      required:
      - name
      - petType
    Cat:  ## "Cat" will be used as the discriminator value
      description: A representation of a cat
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        properties:
          huntingSkill:
            type: string
            description: The measured skill for hunting
            enum:
            - clueless
            - lazy
            - adventurous
            - aggressive
        required:
        - huntingSkill
    Dog:  ## "Dog" will be used as the discriminator value
      description: A representation of a dog
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        properties:
          packSize:
            type: integer
            format: int32
            description: the size of the pack the dog is from
            default: 0
            minimum: 0
        required:
        - packSize

辨別器物件

當請求主體或回應 payload 可以是多個不同 schema 之一時，可以使用 discriminator 物件來協助序列化、反序列化和驗證。辨別器是 schema 中的特定物件，用於根據與之關聯的值，通知規格的使用者關於替代 schema 的資訊。

使用辨別器時，將不會考慮行內 schema。

固定欄位

欄位名稱	類型	描述
propertyName	`字串`	必要。payload 中將保留辨別器值的屬性名稱。
mapping	Map[`string`, `string`]	一個物件，用於保留 payload 值和 schema 名稱或參考之間的對應。

辨別器物件僅在使用複合關鍵字 oneOf、anyOf、allOf 時才是合法的。

在 OAS 3.0 中，回應 payload 可能被描述為恰好是任意數量的類型之一

MyResponseType:
  oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
  - $ref: '#/components/schemas/Lizard'

這表示 payload 必須透過驗證，完全符合 Cat、Dog 或 Lizard 所描述的 schema 之一。在這種情況下，辨別器可以充當「提示」，以縮短驗證時間並選擇匹配的 schema，這可能是一個成本高昂的操作，具體取決於 schema 的複雜性。然後，我們可以準確地描述哪個欄位告訴我們使用哪個 schema

MyResponseType:
  oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
  - $ref: '#/components/schemas/Lizard'
  discriminator:
    propertyName: petType

現在的期望是，回應 payload 中必須存在名為 petType 的屬性，並且該值將對應於 OAS 文件中定義的 schema 名稱。因此，回應 payload

{
  "id": 12345,
  "petType": "Cat"
}

將指示將 Cat schema 與此 payload 一起使用。

在辨別器欄位的值與 schema 名稱不符或無法進行隱式對應的情況下，可以使用選擇性的 mapping 定義

MyResponseType:
  oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
  - $ref: '#/components/schemas/Lizard'
  - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json'
  discriminator:
    propertyName: petType
    mapping:
      dog: '#/components/schemas/Dog'
      monster: 'https://gigantic-server.com/schemas/Monster/schema.json'

在此，dog 的辨別器值將對應到 schema #/components/schemas/Dog，而不是預設（隱式）值 Dog。如果辨別器值與隱式或顯式對應不符，則無法確定 schema，並且驗證應該失敗。對應鍵必須是字串值，但工具可以將回應值轉換為字串以進行比較。

與 anyOf 建構結合使用時，辨別器的使用可以避免多個 schema 可能滿足單個 payload 的情況下的歧義。

在 oneOf 和 anyOf 用例中，必須明確列出所有可能的 schema。為了避免冗餘，辨別器可以添加到父 schema 定義中，並且所有在 allOf 建構中構成父 schema 的 schema 都可以用作替代 schema。

例如

components:
  schemas:
    Pet:
      type: object
      required:
      - petType
      properties:
        petType:
          type: string
      discriminator:
        propertyName: petType
        mapping:
          dog: Dog
    Cat:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Cat`
        properties:
          name:
            type: string
    Dog:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Dog`
        properties:
          bark:
            type: string
    Lizard:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Lizard`
        properties:
          lovesRocks:
            type: boolean

像這樣的 payload

{
  "petType": "Cat",
  "name": "misty"
}

將指示使用 Cat schema。同樣，此 schema

{
  "petType": "dog",
  "bark": "soft"
}

將因為 mappings 元素中的定義而對應到 Dog。

XML 物件

允許更精細的 XML 模型定義的中繼資料物件。

使用陣列時，XML 元素名稱不會推斷（對於單數/複數形式），並且應該使用 name 屬性來新增該資訊。有關預期行為，請參閱範例。

固定欄位

欄位名稱	類型	描述
name	`字串`	取代用於描述的 schema 屬性的元素/屬性的名稱。在 `items` 中定義時，它會影響清單中個別 XML 元素的名稱。在與 `type` 一起定義為 `array` 時（在 `items` 之外），它會影響包裝元素，並且僅當 `wrapped` 為 `true` 時才會影響。如果 `wrapped` 為 `false`，則會忽略它。
namespace	`字串`	命名空間定義的 URI。值必須採用絕對 URI 的形式。
prefix	`字串`	用於 name 的前置詞。
attribute	`布林值`	宣告屬性定義會轉換為屬性而不是元素。預設值為 `false`。
wrapped	`布林值`	可能僅用於陣列定義。表示陣列是否被包裹（例如，`<books><book/><book/></books>`）或未包裹（`<book/><book/>`）。預設值為 `false`。只有在與 `type` 定義為 `array` 時（在 `items` 之外）一起定義時，此定義才會生效。

這個物件可以透過規格擴展進行擴充。

XML 物件範例

XML 物件定義的範例包含在 Schema 物件的屬性定義中，並附有其 XML 表示的範例。

無 XML 元素

基本字串屬性

{
    "animals": {
        "type": "string"
    }
}

animals:
  type: string

<animals>...</animals>

基本字串陣列屬性（wrapped 預設為 false）

{
    "animals": {
        "type": "array",
        "items": {
            "type": "string"
        }
    }
}

animals:
  type: array
  items:
    type: string

<animals>...</animals>
<animals>...</animals>
<animals>...</animals>

XML 名稱替換

{
  "animals": {
    "type": "string",
    "xml": {
      "name": "animal"
    }
  }
}

animals:
  type: string
  xml:
    name: animal

<animal>...</animal>

XML 屬性、前綴和命名空間

在此範例中，顯示了完整的模型定義。

{
  "Person": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int32",
        "xml": {
          "attribute": true
        }
      },
      "name": {
        "type": "string",
        "xml": {
          "namespace": "http://example.com/schema/sample",
          "prefix": "sample"
        }
      }
    }
  }
}

Person:
  type: object
  properties:
    id:
      type: integer
      format: int32
      xml:
        attribute: true
    name:
      type: string
      xml:
        namespace: http://example.com/schema/sample
        prefix: sample

<Person id="123">
    <sample:name xmlns:sample="http://example.com/schema/sample">example</sample:name>
</Person>

XML 陣列

變更元素名稱

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal

<animal>value</animal>
<animal>value</animal>

外部的 name 屬性對 XML 沒有影響

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens"
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens

<animal>value</animal>
<animal>value</animal>

即使陣列被包裹，如果沒有明確定義名稱，內部和外部都會使用相同的名稱

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
  xml:
    wrapped: true

<animals>
  <animals>value</animals>
  <animals>value</animals>
</animals>

為了克服上述範例中的命名問題，可以使用以下定義

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    wrapped: true

<animals>
  <animal>value</animal>
  <animal>value</animal>
</animals>

同時影響內部和外部名稱

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens
    wrapped: true

<aliens>
  <animal>value</animal>
  <animal>value</animal>
</aliens>

如果我們變更外部元素但不變更內部元素

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
  xml:
    name: aliens
    wrapped: true

<aliens>
  <aliens>value</aliens>
  <aliens>value</aliens>
</aliens>

安全機制物件

定義可供操作使用的安全性方案。支援的方案包括 HTTP 驗證、API 金鑰（作為標頭、Cookie 參數或查詢參數）、OAuth2 的常見流程（隱式、密碼、用戶端憑證和授權碼），如 RFC6749 和 OpenID Connect Discovery 中所定義。

固定欄位

欄位名稱	類型	適用於	描述
type	`字串`	任何	必要。安全性方案的類型。有效值為 `"apiKey"`、`"http"`、`"oauth2"`、`"openIdConnect"`。
description	`字串`	任何	安全性方案的簡短描述。CommonMark 語法可用於富文本表示。
name	`字串`	`apiKey`	必要。要使用的標頭、查詢或 Cookie 參數的名稱。
in	`字串`	`apiKey`	必要。API 金鑰的位置。有效值為 `"query"`、`"header"` 或 `"cookie"`。
scheme	`字串`	`http`	必要。要在 RFC7235 中定義的授權標頭中使用的 HTTP 授權方案的名稱。使用的值應在 IANA 驗證方案註冊表中註冊。
bearerFormat	`字串`	`http` (`"bearer"`)	提示用戶端識別 Bearer 令牌的格式。Bearer 令牌通常由授權伺服器產生，因此此資訊主要用於文件目的。
flows	OAuth 流程物件	`oauth2`	必要。包含支援的流程類型之組態資訊的物件。
openIdConnectUrl	`字串`	`openIdConnect`	必要。用於探索 OAuth2 組態值的 OpenId Connect URL。此 URL 必須為 URL 格式。

這個物件可以透過規格擴展進行擴充。

安全性方案物件範例

基本驗證範例

{
  "type": "http",
  "scheme": "basic"
}

type: http
scheme: basic

API 金鑰範例

{
  "type": "apiKey",
  "name": "api_key",
  "in": "header"
}

type: apiKey
name: api_key
in: header

JWT Bearer 範例

{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT",
}

type: http
scheme: bearer
bearerFormat: JWT

隱式 OAuth2 範例

{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

OAuth 流程物件

允許組態支援的 OAuth 流程。

固定欄位

欄位名稱	類型	描述
implicit	OAuth 流程物件	OAuth 隱式流程的組態
password	OAuth 流程物件	OAuth 資源擁有者密碼流程的組態
clientCredentials	OAuth 流程物件	OAuth 用戶端憑證流程的組態。在 OpenAPI 2.0 中先前稱為 `application`。
authorizationCode	OAuth 流程物件	OAuth 授權碼流程的組態。在 OpenAPI 2.0 中先前稱為 `accessCode`。

這個物件可以透過規格擴展進行擴充。

OAuth 流程物件

支援的 OAuth 流程的組態詳細資訊

固定欄位

欄位名稱	類型	適用於	描述
authorizationUrl	`字串`	`oauth2` (`"implicit"`, `"authorizationCode"`)	必要。此流程要使用的授權 URL。此 URL 必須為 URL 格式。
tokenUrl	`字串`	`oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`)	必要。此流程要使用的令牌 URL。此 URL 必須為 URL 格式。
refreshUrl	`字串`	`oauth2`	用於取得重新整理令牌的 URL。此 URL 必須為 URL 格式。
scopes	Map[`string`, `string`]	`oauth2`	必要。OAuth2 安全性方案的可用範圍。範圍名稱與其簡短描述之間的對應。此對應可以為空。

這個物件可以透過規格擴展進行擴充。

OAuth 流程物件範例

{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    },
    "authorizationCode": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "tokenUrl": "https://example.com/api/oauth/token",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets
  authorizationCode:
    authorizationUrl: https://example.com/api/oauth/dialog
    tokenUrl: https://example.com/api/oauth/token
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

安全要求物件

列出執行此操作所需的安全性方案。每個屬性使用的名稱必須對應於元件物件下的安全性方案中宣告的安全性方案。

包含多個方案的安全性需求物件要求必須滿足所有方案，才能授權請求。這使得可以支援需要多個查詢參數或 HTTP 標頭來傳遞安全性資訊的情況。

當在 OpenAPI 物件或操作物件上定義安全性需求物件清單時，只需要滿足清單中的其中一個安全性需求物件即可授權請求。

模式化欄位

欄位模式	類型	描述
{name}	[`string`]	每個名稱必須對應於在元件物件下的安全性方案中宣告的安全性方案。如果安全性方案的類型為 `"oauth2"` 或 `"openIdConnect"`，則該值為執行所需的範圍名稱清單，如果授權不需要指定的範圍，則此清單可以為空。對於其他安全性方案類型，陣列必須為空。

安全性需求物件範例

非 OAuth2 安全性需求

{
  "api_key": []
}

api_key: []

OAuth2 安全性需求

{
  "petstore_auth": [
    "write:pets",
    "read:pets"
  ]
}

petstore_auth:
- write:pets
- read:pets

選用的 OAuth2 安全性

選用的 OAuth2 安全性，如 OpenAPI 物件或操作物件中所定義。

{
  "security": [
    {},
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ]
}

security:
  - {}
  - petstore_auth:
    - write:pets
    - read:pets

規格延伸

雖然 OpenAPI 規格試圖容納大多數使用案例，但可以新增額外的資料以在特定點擴展規格。

擴展屬性以模式化欄位實作，這些欄位一律以 "x-" 為前綴。

欄位模式	類型	描述
^x-	任何	允許擴展 OpenAPI 綱要。欄位名稱必須以 `x-` 開頭，例如 `x-internal-id`。值可以是 `null`、基本值、陣列或物件。可以具有任何有效的 JSON 格式值。

擴展可能受或不受可用工具的支援，但也可能會進行擴展以新增請求的支援（如果工具是內部或開放原始碼）。

安全篩選

OpenAPI 規格中的某些物件可能會宣告並保持空白，甚至會完全移除，即使它們本質上是 API 文件的核心。

這樣做的原因是允許對文件進行額外的存取控制層級。雖然不是規格本身的一部分，但某些程式庫可能會選擇根據某種形式的驗證/授權來允許存取文件的某些部分。

以下是兩個範例

路徑物件可以為空。這可能違反直覺，但這可能會告訴檢視者他們到達了正確的位置，但無法存取任何文件。他們仍然可以存取資訊物件，其中可能包含有關驗證的其他資訊。
路徑項目物件可以為空。在這種情況下，檢視者將知道該路徑存在，但將無法看到其任何操作或參數。這與從路徑物件中隱藏路徑本身不同，因為使用者會知道其存在。這允許文件提供者精確控制檢視者可以查看的內容。

附錄 A：修訂歷程記錄

版本	日期	備註
3.0.3	2020-02-20	OpenAPI 規格 3.0.3 的修補程式版本
3.0.2	2018-10-08	OpenAPI 規格 3.0.2 的修補程式版本
3.0.1	2017-12-06	OpenAPI 規格 3.0.1 的修補程式版本
3.0.0	2017-07-26	OpenAPI 規格 3.0.0 的發佈
3.0.0-rc2	2017-06-16	3.0 規格的 rc2
3.0.0-rc1	2017-04-27	3.0 規格的 rc1
3.0.0-rc0	2017-02-28	3.0 規格的實作者草案
2.0	2015-12-31	將 Swagger 2.0 捐贈給 OpenAPI 計畫
2.0	2014-09-08	Swagger 2.0 的發佈
1.2	2014-03-14	正式文件的初始發佈。
1.1	2012-08-22	Swagger 1.1 的發佈
1.0	2011-08-10	Swagger 規格的第一次發佈

OpenAPI 規格

版本 3.0.3

簡介

目錄

定義

OpenAPI 文件

路徑樣板

媒體類型

HTTP 狀態碼

規格

版本

格式

文件結構

資料類型

豐富文字格式設定

URL 中的相對參考

結構描述

OpenAPI 物件

固定欄位

資訊物件

固定欄位

資訊物件範例

聯絡人物件

固定欄位

聯絡物件範例

授權物件

固定欄位

授權物件範例

伺服器物件

固定欄位

伺服器物件範例

伺服器變數物件

固定欄位

元件物件

固定欄位

元件物件範例

路徑物件

模式化欄位

路徑範本比對

路徑物件範例

路徑項目物件

固定欄位

路徑項目物件範例

操作物件

固定欄位

操作物件範例

外部文件物件

固定欄位

外部文件物件範例

參數物件

參數位置

固定欄位

樣式值

樣式範例

參數物件範例

請求主體物件

固定欄位

請求主體範例

媒體類型物件

固定欄位

媒體類型範例

檔案上傳的考量事項

支援 x-www-form-urlencoded 請求主體

multipart 內容的特殊考量事項

編碼物件

固定欄位

編碼物件範例

回應物件

固定欄位

模式化欄位

回應物件範例

回應物件

固定欄位

回應物件範例

回呼物件

模式化欄位

鍵值表達式

回呼物件範例

範例物件

固定欄位

`multipart` 內容的特殊考量事項