一、OpenAPI 规范

OpenAPI 3.0.0 是 OpenAPI 规范的第一个正式版本,因为它是由 SmartBear Software 捐赠给 OpenAPI Initiative,并在2015年从 Swagger 规范重命名为 OpenAPI 规范。

1.1 版本 3.0.0

文档里的关键词 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" 都遵循 BCP 14 RFC2119 RFC8174 里的解释说明。

本文档 License: The Apache License, Version 2.0.

二、介绍

OpenAPI 规范(OAS),是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。如果您在定义您的 API 时做的很好,那么使用 API 的人就能非常轻松地理解您提供的 API 并与之交互了。

如果您遵循 OpenAPI 规范来定义您的 API,那么您就可以用文档生成工具来展示您的 API,用代码生成工具来自动生成各种编程语言的服务器端和客户端的代码,用自动测试工具进行测试等等。

三、术语定义

3.1 OpenAPI 文档

一(或多)份用来定义或描述一个API的文档。

3.2 Path 模板

Path 模板指用大括号标记来标记一段 URL 作为可替换的路径参数。

3.3 Media Types

媒体类型定义分散于多处。 媒体类型定义应当符合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
3.4 HTTP状态码

HTTP状态码被用来表示一次请求的被执行状态。RFC7231定义了有效的状态码,可以在IANA Status Code Registry找到已经被注册的状态码的列表。

四、规范

版本

开放API规范使用符合语义化版本 2.0.0(semver)规范的版本号。

语义化版本的主版本号次版本号部分(比如3.0)应当被用来标记开放API规范的特性变动。通常 .修订号 版本被用来表示本文档文档的错误修正而不是特性变动。支持开放API规范3.0的工具应该兼容所有3.0.*的版本,工具不应当关注修订版本号,比如3.0.03.0.1对它来说应该没有任何区别。

此后开放API规范的相同主版本号下更高次要版本的发布不应当对面向低于此次要版本号开发的工具的造成干扰。因此3.1.0版本的规范应当可以在面向3.0.0版本规范开发的工具内使用。

任何兼容开放API规范 3.*.* 的文档应当包含一个openapi 字段用来表明它使用的规范的语义化版本。

格式

一份遵从开放API规范的文档是一个自包含的JSON对象,可以使用JSON或YAML格式编写。

比如一个字段有一组值,用JSON格式表示为:

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

规范内的所有字段名都是小写

字段分为两种:固定字段和模式字段。固定字段的字段名是确定的,模式字段的字段名需要符合一定的模式。

如果一个对象里有模式字段,那么在这个对象里的模式字段的名字不能有重复的。

为了保留在 YAML 和 JSON 格式之间转换的能力,推荐使用1.2版本的YAML格式,而且还需要符合以下限制:

注意: 虽然API文档是使用 YAML 或 JSON 格式书写的,但是API的请求体和响应体或者其他内容可以是任何格式。

文档结构

一份 OpenAPI 文档可以是单个文件也可以被拆分为多个文件, 连接的部分由用户自行决定。在后一种情形下,必须如 JSON Schema 中定义的那样使用 $ref 字段来相互引用。

推荐将根 OpenAPI 文档命名为openapi.jsonopenapi.yaml

数据类型

在 OAS 中的原始数据类型是基于 JSON Schema Specification Wright Draft 00 所支持的类型。注意 integer 也作为一个被支持的类型并被定义为不包含小数或指数部分的 JSON 数字。null 不是一个被支持的类型 (查看 nullable 来获得替代解决方案)。 Models 使用 Schema 对象 定义,这是一个 JSON Schema Specification Wright Draft 00 的扩展。

原始类型可以有一个可选的修饰属性:format。 OAS 使用多个已知的格式来丰富类型定义。尽管如此,为了文档的需要,format 属性被设计为一个 string 类型的开放属性值,可以包含任意值。比如 "email", "uuid" 等未被此规范定义的格式也可以被使用。没有被定义的 format 属性类型遵从 JSON Schema 中的类型定义。无法识别某个 format 值的工具应该回退到 type 值,就像 format 未被指定一样。

被 OAS 定义的格式:

通用名typeformat备注
integerintegerint3232 位有符号
longintegerint6464 位有符号
floatnumberfloat
doublenumberdouble
stringstring
bytestringbytebase64 编码的支付
binarystringbinary任意 8进制序列
booleanboolean
datestringdate定义于 full-date - RFC3339
dateTimestringdate-time定义于 date-time - RFC3339
passwordstringpassword告知输入界面不应该明文显示输入信息。

富文本格式

整个规范中的 description 字段被标记为支持 CommonMark markdown 格式。 OpenAPI 相关的工具在支持 CommonMark 0.27 中描述的富文本格式方面至少需要支持渲染 markerdown。相关工具为了安全考虑可以选择忽略某些 CommonMark 特性。

URL 的关联引用

除非明确指定,所有 URL 类型的属性值都可以是相对地址,就如 RFC3986 中定义的那样以 Server 对象 作为 Base URI。

$ref 中的相对引用以 JSON Reference 为依据,以当前文档的 URL 作为 base URI. 同时参考 Reference 对象

五、数据结构

在接下来的叙述中,如果一个字段没有被明确的标记为 必选 或者被描述为 必须应当,那么可以认为它是一个 可选 字段

OpenAPI 对象

这是OpenAPI document的根文档对象。

固定字段
字段名类型描述
openapistring必选. 这个字符串必须是开放API规范版本号提到的符合语义化版本号规范的版本号。openapi字段应该被工具或者客户端用来解释 OpenAPI 文档。这个值和API info.version字符串没有关联。
infoInfo 对象必选。此字段提供API相关的元数据。相关工具可能需要这个字段。
servers[Server 对象]这是一个Server对象的数组, 提供到服务器的连接信息。如果没有提供servers属性或者是一个空数组,那么默认为是url值为/Server 对象
pathsPaths 对象必选。对所提供的API有效的路径和操作。
componentsComponents 对象一个包含多种结构的元素。
security[Security Requirement 对象]声明API使用的安全机制。The list of values includes alternative security requirement objects that can be used. 认证一个请求时仅允许使用一种安全机制。单独的操作可以覆盖这里的定义。
tags[Tag 对象]提供更多元数据的一系列标签,标签的顺序可以被转换工具用来决定API的顺序。不是所有被Operation 对象用到的标签都必须被声明。没有被声明的标签可能被工具按自己的逻辑任意整理,每个标签名都应该是唯一的。
externalDocsExternal Documentation 对象附加的文档。这个对象可能会被规范扩展扩展。

Info 对象

这个对象提供API的元数据。如果客户端需要时可能会用到这些元数据,而且可能会被呈现在编辑工具或者文档生成工具中。

固定字段
字段名类型描述
titlestring必选. 应用的名称。
descriptionstring对应用的简短描述。 CommonMark syntax 可以被用来表示富文本呈现。
termsOfServicestring指向服务条款的URL地址,必须是URL地址格式。
contactContact 对象所开放的API的联系人信息。
licenseLicense 对象所开放的API的证书信息。
versionstring必选. API文档的版本信息(注意:这个版本和开放API规范版本没有任何关系)。
Info 对象示例
{
"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": "support@example.com"
},
"license": {
"name": "Apache 2.0",
"url": "http://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: support@example.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

Contact 对象

所公开的API的联系人信息

固定字段
字段名类型描述
namestring人或组织的名称。
urlstring指向联系人信息的URL地址,必须是URL地址格式。
emailstring人或组织的email地址,必须是email地址格式。

这个对象可能会被规范扩展扩展。

Contact 对象示例
{
"name": "API Support",
"url": "http://www.example.com/support",
"email": "support@example.com"
}
name: API Support
url: http://www.example.com/support
email: support@example.com

License 对象

公开API的证书信息。

固定字段
字段名类型描述
namestring必选. API的证书名。
urlstring指向API所使用的证书的URL地址,必须是URL地址格式。

这个对象可能会被规范扩展扩展。

License 对象示例
{
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html

Server 对象

表示一个服务器的对象。

固定字段
字段名类型描述
urlstring必选. 指向目标主机的URL地址。这个URL地址支持服务器变量而且可能是相对路径,表示主机路径是相对于本文档所在的路径。当一个变量被命名为类似{brackets}时需要替换此变量。
descriptionstring一个可选的字符串,用来描述此URL地址。CommonMark syntax可以被用来呈现富文本格式.
variablesMap[string, Server Variable 对象]一组变量和值的映射,这些值被用来替换服务器URL地址内的模板参数。

这个对象可能会被规范扩展扩展。

Server 对象示例

单个服务器可以这样描述:

{
"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

Server Variable 对象

表示可用于服务器URL地址模板变量替换的对象。

固定字段
字段名类型描述
enum[string]一组可枚举字符串值,当可替换选项只能设置为固定的某些值时使用。
defaultstring必选. 当可替换的值没有被使用者指定时使用的默认值。不像Schema 对象'sdefault ,这个值必须由使用者提供。
descriptionstring对服务器变量的可选的描述。CommonMark syntax可以被用来呈现富文本格式.

这个对象可能会被规范扩展扩展。

Components 对象

包含开放API规范固定的各种可重用组件。当没有被其他对象引用时,在这里定义定义的组件不会产生任何效果。

固定字段
字段名类型描述
schemasMap[string, Schema 对象 | Reference 对象]定义可重用的 Schema 对象 的对象。
responsesMap[string, Response 对象 | Reference 对象]定义可重用的 Response 对象 的对象。
parametersMap[string, Parameter 对象 | Reference 对象]定义可重用的 Parameter 对象 的对象。
examplesMap[string, Example 对象 | Reference 对象]定义可重用的 Example 对象 的对象。
requestBodiesMap[string, Request Body 对象 | Reference 对象]定义可重用的 Request Body 对象 的对象。
headersMap[string, Header 对象 | Reference 对象]定义可重用的 Header 对象 的对象。
securitySchemesMap[string, Security Scheme 对象 | Reference 对象]定义可重用的 Security Scheme 对象 的对象。
linksMap[string, Link 对象 | Reference 对象]定义可重用的 Link 对象 的对象。
callbacksMap[string, Callback 对象 | Reference 对象]定义可重用的 Callback 对象 的对象。

这个对象可能会被 规范扩展 扩展。

上面定义的所有固定字段的值都是对象,对象包含的key的命名必须满足正则表达式: ^[a-zA-Z0-9\.\-_]+$

字段名示例:

User
User_1
User_Name
user-name
my.org.User
Components 对象示例
"components": {
"schemas": {
"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:
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

Paths 对象

定义各个的端点和操作的相对路径。这里指定的路径会和 Server 对象 内指定的URL地址组成完整的URL地址,路径可以为空,这依赖于 ACL constraints 的设置。

模式字段
字段名模式类型描述
/{path}Path Item 对象到各个端点的相对路径,路径必须以/打头,这个路径会被直接连接Server 对象url字段以组成完整URL地址(不会考虑是否是相对路径)。这里可以使用 Path templating ,当做URL地址匹配时,不带路径参数的路径会被优先匹配。应该避免定义多个具有相同路径层级但是路径参数名不同的路径,因为他们是等价的。当匹配出现歧义时,由使用的工具自行决定使用那个路径。

这个对象可能会被规范扩展扩展。

路径模板匹配

假设有以下路径,明确定义的路径 /pets/mine 会被优先匹配:

/pets/{petId}
/pets/mine

以下路径被认为是等价的而且是无效的:

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

以下路径会产生歧义:

/{entity}/me
/books/{id}
Paths 对象示例
{
"/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'

Path Item 对象

描述对一个路径可执行的有效操作。依赖与 ACL constraints 的设置,一个Path Item可以是一个空对象,文档的读者仍然可以看到这个路径,但是他们将无法了解到对这个路径可用的任何操作和参数。

固定字段
字段名类型描述
$refstring指定对此路径的外部定义的引用,引用的格式必须符合 Path Item 对象 的格式,如果引用的外部定义和此对象内的其他定义有冲突,该如何处理冲突尚未被定义。
summarystring一个可选的简要总结字符串,用来描述此路径内包含的所有操作。
descriptionstring一个可选的详细说明字符串,用于描述此路径包含的所有操作。 CommonMark syntax可以被用来呈现富文本格式.
getOperation 对象定义适用于此路径的 GET 操作。
putOperation 对象定义适用于此路径的 PUT 操作。
postOperation 对象定义适用于此路径的 POST 操作.
deleteOperation 对象定义适用于此路径的 DELETE 操作。
optionsOperation 对象定义适用于此路径的 OPTIONS 操作。
headOperation 对象定义适用于此路径的 HEAD 操作。
patchOperation 对象定义适用于此路径的 PATCH 操作。
traceOperation 对象定义适用于此路径的 TRACE 操作。
servers[Server 对象]一个可用于此路径所有操作的替代根server的数组定义。
parameters[Parameter 对象 | Reference 对象]一个可用于此路径下所有操作的参数的列表。这些参数可以被具体的操作定义覆盖,但是不能被移除。这个列表禁止包含重复的参数,一个唯一的参数名由 namelocation 的组合来定义。这个列表可以使用 Reference 格式引用定义在 OpenAPI 对象 components/parameters 内的参数。

这个对象可能会被规范扩展扩展。

Path Item 对象示例
{
"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
style: simple
items:
type: string

Operation 对象

描述对路径的某个操作。

固定字段
字段名类型描述
tags[string]用于控制API文档的标签列表,标签可以用于在逻辑上分组对资源的操作或作为其它用途的先决条件。
summarystring对此操作行为的简短描述。
descriptionstring对此操作行为的详细解释。CommonMark syntax可以被用来呈现富文本格式.
externalDocsExternal Documentation 对象附加的外部文档。
operationIdstring用于标识此操作的唯一字符串,这个id在此API内包含的所有操作中必须是唯一的。相关的工具和库可能会使用此operationId来唯一的标识一个操作,因此推荐在命名时符合一般的编程命名习惯。
parameters[Parameter 对象 | Reference 对象]定义可用于此操作的参数列表,如果一个同名的参数已经存在于 Path Item,那么这里的定义会覆盖它但是不能移除上面的定义。这个列表不允许包含重复的参数,参数的唯一性由 namelocation 的组合来确定。这个列表可以使用 Reference 对象 来连接定义于 OpenAPI 对象 components/parameters 的参数。
requestBodyRequest Body 对象 | Reference 对象可用于此操作的请求体。requestBody 只能被用于HTTP 1.1 规范 RFC7231 中明确定义了包含请求体的请求方法,在其他没有明确定义的请求方法中,requestBody的消费者应该应该忽略requestBody
responsesResponses 对象必选. 定义执行此操作后的可能的响应值列表。
callbacksMap[string, Callback 对象 | Reference 对象]一组相对于父操作的可能出现的回调映射,A map of possible out-of band callbacks related to the parent operation. 映射中的每一个键都唯一的映射一个 Callback 对象, that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
deprecatedboolean声明此操作已经被废弃,使用者应该尽量避免使用此操作,默认的值是 false
security[Security Requirement 对象]声明那种安全机制可用于此操作。这个列表可以包含多种可用于此操作的安全需求对象,但是在认证一个请求时应该仅使用其中一种。这里的定义会覆盖任何在顶层 security 中的安全声明,因此可以声明一个空数组来变相的移除顶层的安全声明。
servers[Server 对象]一个可用于此操作的额外的 server 数组,这里的定义会覆盖 Path Item 对象 或 顶层的定义。

这个对象可能会被规范扩展扩展。

Operation 对象示例
{
"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": "Invalid input",
"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: Invalid input
content:
'application/json': {}
'application/xml': {}
security:
- petstore_auth:
- write:pets
- read:pets

External Documentation 对象

允许引用外部资源来扩展文档。

固定字段
字段名类型描述
descriptionstring对引用的外部文档的简短描述。CommonMark syntax可以被用来呈现富文本格式.
urlstring必选. 外部文档的URL地址,这个值必须是URL地址格式。

这个对象可能会被规范扩展扩展。

External Documentation 对象示例
{
"description": "Find more info here",
"url": "https://example.com"
}
description: Find more info here
url: https://example.com

Parameter 对象

描述一个操作参数。

一个参数的唯一性由 namelocation 的组合来确定。

参数位置

有4种可能的参数位置值可用于in字段:

  • path - 与 Path Templating 一起使用,当参数的值是URL操作路径的一部分时可以使用,但是不包含主机地址或基础路径。比如在路径 /items/{itemId} 中,路径参数是 itemId
  • query - 追加在URL地址之后的参数,比如 /items?id=### 中,查询参数是 id
  • header - 请求中使用的自定义请求头,注意在 RFC7230 中规定,请求头的命名是不区分大小写的。
  • cookie - 用于传递特定的cookie值。
固定字段
字段名类型描述
namestring必选. 参数的名称。参数名是区分大小写
  • 如果 in 的值是 "path",那么 name 字段的值必须与其关联的 Paths 对象path 字段的定义相呼应,查看 Path Templating 了解更多信息。
  • 如果 in 的值是 "header" 而且name字段的值是"Accept", "Content-Type""Authorization"之一,那么此参数定义应该被忽略。
  • 除此之外的情况,name表示 in 属性的名字.
instring必选. 参数的位置,可能的值有 "query", "header", "path" 或 "cookie"。
descriptionstring对此参数的简要描述,这里可以包含使用示例。CommonMark syntax可以被用来呈现富文本格式.
requiredboolean标明此参数是否是必选参数。如果 参数位置 的值是 path,那么这个参数一定是 必选 的因此这里的值必须是true。其他的则视情况而定。此字段的默认值是false
deprecatedboolean标明一个参数是被弃用的而且应该尽快移除对它的使用。
allowEmptyValueboolean设置是否允许传递空参数,这只在参数值为query时有效,默认值是false。如果同时指定了style属性且值为n/a(无法被序列化),那么此字段 allowEmptyValue应该被忽略。

序列化参数的规则有两种。 对于简单的场景, schemastyle 可以用于描述参数的结构和语法。

字段名类型描述
stylestring描述根据参数值类型的不同如何序列化参数。默认值为(基于in字段的值):query 对应 formpath 对应 simple; header 对应 simple; cookie 对应 form
explodeboolean当这个值为true时,参数值类型为arrayobject的参数使用数组内的值或对象的键值对生成带分隔符的参数值。对于其他类型的参数,这个字段没有任何影响。当 styleform时,这里的默认值是 true,对于其他 style 值类型,默认值是false
allowReservedboolean决定此参数的值是否允许不使用%号编码使用定义于 RFC3986内的保留字符 :/?#[]@!$&'()*+,;=。 这个属性仅用于in的值是query时,此字段的默认值是false
schemaSchema 对象 | Reference 对象定义适用于此参数的类型结构。
exampleAny不同媒体类型的示例,示例应该符合响应的结构的编码属性。各个example之间应该是独立的,而且如果一个引用的schema也包含一个示例,那么这里定义的示例应该 覆盖 schema包含的示例。为了展现无法被恰当的用 JSON 或 YAML 格式展现的示例时,可以使用经过必要的编码的字符串值。
examplesMap[ string, Example 对象 | Reference 对象]不同媒体类型的示例。每个示例应该包含一个对应于指定编码格式的格式正确的值,这个examples映射内包含的对象应该不同于example内的值。而且如果一个引用的schema也包含一个示例,那么这里定义的示例应该 覆盖 schema包含的示例。

对于更复杂的场景,content属性可以定义参数的媒体类型和概要。一个参数必须且只能包含schemacontent属性中的一个。当exampleexamples字段提供了schema对象时,示例必须遵照参数的序列化策略。

字段名类型描述
contentMap[string, Media Type 对象]一个定义参数如何呈现的键值对映射。键是媒体类型,值是对应媒体类型的示例数据,此键值对只能包含一组键值对。
样式值

已经定义好了一组style类型用于支持常见的通用的简单参数序列化。

样式类型in描述
matrixprimitive, array, objectpathPath 样式的参数,参见 RFC6570
labelprimitive, array, objectpathLabel 样式的参数,参见 RFC6570
formprimitive, array, objectquery, cookieForm 样式的参数,参见 RFC6570. 此选项替换定义于OpenAPI 2.0中collectionFormat等于csv (当 explode值为 false)或multi (当 explode值为 true)的情况。
simplearraypath, headerSimple 样式的参数,参见 RFC6570. 此选项替换定义于OpenAPI 2.0 中 collectionFormat等于csv的情况。
spaceDelimitedarrayquery空格分隔的数组值。此选项替换定义于OpenAPI 2.0 中 collectionFormat equal to ssv的情况。
pipeDelimitedarrayquery管道符`
deepObjectobjectquery提供一种简单的方法来表示参数中的嵌套对象值.
Style 示例

建设一个参数名为color包含如下之一的值:

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

下面这个表展示了各个不同类型值之间的例子。

styleexplodeemptystringarrayobject
matrixfalse;color;color=blue;color=blue,black,brown;color=R,100,G,200,B,150
matrixtrue;color;color=blue;color=blue;color=black;color=brown;R=100;G=200;B=150
labelfalse..blue.blue.black.brown.R.100.G.200.B.150
labeltrue..blue.blue.black.brown.R=100.G=200.B=150
formfalsecolor=color=bluecolor=blue,black,browncolor=R,100,G,200,B,150
formtruecolor=color=bluecolor=blue&color=black&color=brownR=100&G=200&B=150
simplefalsen/ablueblue,black,brownR,100,G,200,B,150
simpletruen/ablueblue,black,brownR=100,G=200,B=150
spaceDelimitedfalsen/an/ablue%20black%20brownR%20100%20G%20200%20B%20150
pipeDelimitedfalsen/an/ablue|black|brownR|100|G|200
deepObjecttruen/an/an/acolor[R]=100&color[G]=200&color[B]=150

这个对象可能会被规范扩展扩展。

Parameter 对象示例

一个值数组,数组元素为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

Request Body 对象

定义请求体。

固定字段
字段名类型描述
descriptionstring对请求体的简要描述,可以包含使用示例,CommonMark syntax可以被用来呈现富文本格式.
contentMap[string, Media Type 对象]必选. 请求体的内容。请求体的属性key是一个媒体类型或者媒体类型范围,值是对应媒体类型的示例数据。对于能匹配多个key的请求,定义更明确的请求会更优先被匹配。比如text/plain会覆盖text/*的定义。
requiredboolean指定请求体是不是应该被包含在请求中,默认值是false

这个对象可能会被规范扩展扩展。

Request Body 示例

一个引用了模型定义的请求体。

{
"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

Media Type 对象

每种媒体类型对象都有相应的结构和示例来描述它。

固定字段
字段名类型描述
schemaSchema 对象 | Reference 对象定义此媒体类型的结构。
exampleAny媒体类型的示例。示例对象应该符合此媒体类型的格式, 这里指定的example对象 object is mutually exclusive of the examples object. 而且如果引用的schema也包含示例,在这里指定的example值将会覆盖schema提供的示例。
examplesMap[ string, Example 对象 | Reference 对象]媒体类型的示例,每个媒体对象的值都应该匹配它对应的媒体类型的格式。 The examples object is mutually exclusive of the example object. 而且如果引用的schema也包含示例,在这里指定的example值将会覆盖schema提供的示例。
encodingMap[string, Encoding 对象]属性名与编码信息的映射。每个属性名必须存在于schema属性的key中,当媒体类型等于multipartapplication/x-www-form-urlencoded时,编码对象信息仅适用于requestBody

这个对象可能会被规范扩展扩展。

Media Type 示例
{
"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的规范,file内容的上传与下载在开放API规范与其他类型一样使用相同的语法来描述。 特别的是:

# 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:
# any media type is accepted, functionally equivalent to `*/*`
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 请求体的支持

可以使用下面定义的格式来提交form url编码RFC1866的内容:

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格式传送复杂对象时,默认的序列化策略在Encoding 对象style 属性中定义为form.

multipart内容的特别思考

使用multipart/form-data作为Content-Type来传送请求体是很常见的做法。相对于2.0版本的规范,当定义multipart内容的输入参数时必须指定schema属性。这不但支持复杂的结构而且支持多文件上传机制。

当使用multipart类型是,可以使用boundaries来分隔传送的内容,因此multipart定义了以下默认的Content-Type

  • 如果属性是一个原始值或者是一个原始值的数组,那么默认的Content-Type是 text/plain
  • 如果属性是复杂对象或者复杂对象的数组,那么默认的Content-Type是application/json
  • 如果属性是type: stringformat: binaryformat: base64(也就是文件对象)的组合,那么默认的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'

这里介绍一下用来控制序列化multipart请求体的encoding属性,这个属性只适用于multipartapplication/x-www-form-urlencoded类型的请求体。

Encoding 对象

一个编码定义仅适用于一个结构属性。

固定字段
字段名类型描述
contentTypestring对具体属性的 Content-Type的编码。默认值取决于属性的类型:application/octet-stream编码适用于binary格式的stringtext/plain适用于其他原始值;application/json适用于object;对于array值类型的默认值取决于数组内元素的类型,默认值可以是明确的媒体类型(比如application/json), 或者通配符类型的媒体类型(比如image/*), 又或者是用分号分隔的两种媒体类型。
headersMap[string, Header 对象 | Reference 对象]提供附加信息的请求头键值对映射。比如Content-DispositionContent-Type各自描述了不同的信息而且在这里将会被忽略,如果请求体的媒体类型不是multipart,这个属性将会被忽略。
stylestring描述一个属性根据它的类型将会被如何序列化。查看Parameter 对象style属性可以得到更多详细信息。这个属性的行为与query参数相同,包括默认值的定义。如果请求体的媒体类型不是application/x-www-form-urlencoded,这个属性将会被忽略。
explodeboolean当这个值为true时,类型为arrayobject的属性值会为数组的每个元素或对象的每个键值对分开生成参数。这个属性对其他数据类型没有影响。当styleform时,这个属性的默认值是true,对于其他的style类型,这个属性的默认值是false。这个属性会被忽略如果请求体的媒体类型不是application/x-www-form-urlencoded
allowReservedboolean决定此参数的值是否允许不使用%号编码使用定义于 RFC3986内的保留字符 :/?#[]@!$&'()*+,;=。 这个属性仅用于in的值是query时,此字段的默认值是false。 这个属性会被忽略如果请求体的媒体类型不是application/x-www-form-urlencoded

这个对象可能会被规范扩展扩展。

Encoding 对象示例
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

Responses 对象

描述一个操作可能发生的响应的响应码与响应包含的响应体的对象。

一份API文档不必包含所有可能响应码,因为有些状态码无法提前预知。尽管如此,一份文档还是应当包含所有成功的响应和任何已知的错误响应。

default字段可以用来标记一个响应适用于其他未被规范明确定义的HTTP响应码的默认响应。

一个Responses 对象必须至少包含一个响应码,而且是成功的响应。

固定字段
字段名类型描述
defaultResponse 对象 | Reference 对象用于描述未被明确声明的HTTP响应码的响应的文档。使用这个字段来覆盖未声明的响应。一个 Reference 对象 可以链接定义于 OpenAPI 对象 components/responses 区域的响应对象。
模式字段
字段名模式类型描述
HTTP Status CodeResponse 对象 | Reference 对象任何 HTTP status code 都可以被用作属性名, 但是每一个状态码只能使用一次,用于描述此状态码的响应。一个 Reference 对象 可以链接定义于 OpenAPI 对象 components/responses 区域的响应对象。这个字段名必须包含在双引号中 (例如 "200") 以兼容 JSON 和 YAML。这个字段可以包含大写的通配字符X来定义响应码的范围。例如,2XX 代表所有位于 [200-299] 范围内的响应码。只允许使用以下范围定义:1XX, 2XX, 3XX, 4XX, 和 5XX。如果同时包含范围定义与明确定义的响应,那么明确定义的响应有更高的优先级。

这个对象可能会被规范扩展扩展。

Responses 对象示例

一个代表成功操作的 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'

Response 对象

描述单个API操作的响应,包括设计时间、基于不同响应也包括到相应操作的静态links

固定字段
字段名类型描述
descriptionstring必选. 对响应的简短描述。CommonMark syntax可以被用来呈现富文本格式.
headersMap[string, Header 对象 | Reference 对象]映射HTTP头名称到其定义。RFC7230 规定了HTTP头名称不区分大小写。如果一个响应头使用"Content-Type"作为HTTP头名称,它会被忽略。
contentMap[string, Media Type 对象]一个包含描述预期响应负载的映射。使用 media type 或 media type range 作为键,以响应的描述作为值。当一个响应匹配多个键时,只有最明确的键才适用。比如:text/plain 会覆盖 text/*
linksMap[string, Link 对象 | Reference 对象]A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for Component 对象.

这个对象可能会被规范扩展扩展。

Response 对象示例s

一个包含复杂类型的数组格式的响应:

{
"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
representations:
text/plain:
schema:
type: string

带HTTP头的普通文本类型的响应:

{
"description": "A simple string response",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
},
"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

Callback 对象

A map of possible out-of band callbacks related to the parent operation. 映射中的每个值都是一个描述一组可能会被API提供者发起的请求和相应的响应的 Path Item 对象 。用以标识回调对象的键是一个表达式,表达式会在运行时被计算,得到的值作为回调操作的URL。

模式字段
字段名模式类型描述
{expression}Path Item 对象一个用于定义回调请求和响应的 Path Item 对象。 A complete example is available.

这个对象可能会被规范扩展扩展。

Key Expression

用于标识 Path Item 对象 的键是一个 runtime expression,此表达式会在运行时的HTTP请求/响应上下文中被计算,计算结果用于表示回调请求的URL。 一个简单的例子是 $request.body#/url。 However, using a runtime expression the complete HTTP message can be accessed. This includes accessing any part of a body that a JSON Pointer RFC6901 can reference.

比如有如下 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 的查询参数。

ExpressionValue
$url[http://example.org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning]
$methodPOST
$request.path.eventTypemyevent
$request.query.queryUrl[http://clientdomain.com/stillrunning]
$request.header.content-Typeapplication/json
$request.body#/failedUrl[http://clientdomain.com/stillrunning]
$request.body#/successUrls/2[http://clientdomain.com/medium]
$response.header.Location[http://example.org/subscription/1]
Callback 对象示例

如下示例展示了一个通过请求体内的 idemail 属性指定的URL的回调。

myWebhook:
'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: webhook successfully processed and no retries will be performed

Example 对象

固定字段
字段名类型描述
summarystringexample 的简要描述。
descriptionstringexample 的详细描述。CommonMark syntax可以被用来呈现富文本格式.
valueAny嵌入的字面量 example。 value 字段和 externalValue 字段是互斥的。无法使用 JSON 或 YAML 表示的媒体类型可以使用字符串值来表示。
externalValuestring指向字面 exmaple 的一个 URL。这提供了引用无法被包含在 JSON 或 YAML 文档中的 example。value 字段和 externalValue 字段是互斥的。

这个对象可能会被规范扩展扩展。

In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible.

Example 对象示例
# in a model
schemas:
properties:
name:
type: string
examples:
name:
$ref: http://example.org/petapi-examples/openapi.json#/components/examples/name-example
# in a request body:
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'
# in a parameter
parameters:
- name: 'zipCode'
in: 'query'
schema:
type: 'string'
format: 'zip-code'
examples:
zip-example:
$ref: '#/components/examples/zip-example'
# in a response
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'

The Link 对象 represents a possible design-time link for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.

Unlike dynamic links (i.e. links provided in the response payload), the OAS linking mechanism does not require link information in the runtime response.

For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation.

固定字段
字段名Type描述
operationRefstringA relative or absolute reference to an OAS operation. This field is mutually exclusive of the operationId field, and MUST point to an Operation 对象. Relative operationRef values MAY be used to locate an existing Operation 对象 in the OpenAPI definition.
operationIdstringThe name of an existing, resolvable OAS operation, as defined with a unique operationId. This field is mutually exclusive of the operationRef field.
parametersMap[string, Any | {expression}]A map representing parameters to pass to an operation as specified with operationId or identified via operationRef. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. The parameter name can be qualified using the parameter location [{in}.]{name} for operations that use the same parameter name in different locations (e.g. path.id).
requestBodyAny | {expression}A literal value or {expression} to use as a request body when calling the target operation.
descriptionstringA description of the link. CommonMark syntax可以被用来呈现富文本格式.
serverServer 对象A server object to be used by the target operation.

这个对象可能会被规范扩展扩展。

A linked operation MUST be identified using either an operationRef or operationId. In the case of an operationId, it MUST be unique and resolved in the scope of the OAS document. Because of the potential for name clashes, the operationRef syntax is preferred for specifications with external references.

Examples

Computing a link from a request operation where the $request.path.id is used to pass a request parameter to the linked operation.

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

When a runtime expression fails to evaluate, no parameter value is passed to the target operation.

Values from the response body can be used to drive a linked operation.

links:
address:
operationId: getUserAddressByUUID
parameters:
# get the `id` field from the request path parameter named `id`
userUuid: $response.body#/uuid

Clients follow all links at their discretion. Neither permissions, nor the capability to make a successful call to that link, is guaranteed solely by the existence of a relationship.

OperationRef Examples

As references to operationId MAY NOT be possible (the operationId is an optional value), references MAY also be made through a relative operationRef:

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

or an absolute 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

Note that in the use of operationRef, the escaped forward-slash is necessary when using JSON references.

Runtime Expressions

Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by Link 对象 and Callback 对象.

The runtime expression is defined by the following ABNF syntax

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" ["#" fragment]
fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901)
name = *( char )
char = as per RFC [7159](https://tools.ietf.org/html/rfc7159#section-7)
token = as per RFC [7230](https://tools.ietf.org/html/rfc7230#section-3.2.6)

The name identifier is case-sensitive, whereas token is not.

The table below provides examples of runtime expressions and examples of their use in a value:

Examples
Source Locationexample expressionnotes
HTTP Method$methodThe allowable values for the $method will be those for the HTTP operation.
Requested media type$request.header.accept
Request parameter$request.path.idRequest parameters MUST be declared in the parameters section of the parent operation or they cannot be evaluated. This includes request headers.
Request body property$request.body#/user/uuidIn operations which accept payloads, references may be made to portions of the requestBody or the entire body.
Request URL$url
Response value$response.body#/statusIn operations which return payloads, references may be made to portions of the response body or the entire body.
Response header$response.header.ServerSingle header values only are available

Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with {} curly braces.

Header 对象

Header 对象除了以下改动之外与 Parameter 对象 一致:

  1. name 不能被指定,它在相应的 headers 映射中被指定。
  2. in 不能被指定,它隐含在 header 中。
  3. 所有被 location 影响的特性必须适合 header 中的一个 location,(比如 style)。
Header 对象示例

一个类型为 integer 的简单 header:

{
"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

Tag 对象

Adds metadata to a single tag that is used by the Operation 对象. It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.

固定字段
字段名类型描述
namestring必选. The name of the tag.
descriptionstringA short description for the tag. CommonMark syntax可以被用来呈现富文本格式.
externalDocsExternal Documentation 对象Additional external documentation for this tag.

这个对象可能会被规范扩展扩展。

Tag 对象示例
{
"name": "pet",
"description": "Pets operations"
}
name: pet
description: Pets operations

Examples 对象

In an example, a JSON Reference MAY be used, with the explicit restriction that examples having a JSON format with object named$ref are not allowed. Therefore, that example, structurally, can be either a string primitive or an object, similar to additionalProperties.

In all cases, the payload is expected to be compatible with the type schema for the associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if they are incompatible.

# in a model
schemas:
properties:
name:
type: string
example:
$ref: http://foo.bar#/examples/name-example
# in a request body, note the plural `examples`
requestBody:
content:
'application/json':
schema:
$ref: '#/components/schemas/Address'
examples:
foo:
value: {"foo": "bar"}
bar:
value: {"bar": "baz"}
'application/xml':
examples:
xml:
externalValue: 'http://foo.bar/examples/address-example.xml'
'text/plain':
examples:
text:
externalValue: 'http://foo.bar/examples/address-example.txt'
# in a parameter
parameters:
- name: 'zipCode'
in: 'query'
schema:
type: 'string'
format: 'zip-code'
example:
$ref: 'http://foo.bar#/examples/zip-example'
# in a response, note the singular `example`:
responses:
'200':
description: your car appointment has been booked
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
example:
$ref: http://foo.bar#/examples/address-example.json

Reference 对象

一个允许引用规范内部的其他部分或外部规范的对象。

Reference 对象 定义于 JSON Reference 且遵循相同的结构、行为和规则。

For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification.

固定字段
字段名类型描述
$refstring必选. 引用字符串。

此对象不能被扩展,任何附加的属性将会被忽略。

Reference 对象示例
{
"$ref": "#/components/schemas/Pet"
}
$ref: '#/components/schemas/Pet'
关联外部文档示例
{
"$ref": "Pet.json"
}
$ref: Pet.yaml
关联外部文档的一部分
{
"$ref": "definitions.json#/Pet"
}
$ref: definitions.yaml#/Pet

Schema 对象

Schema 对象 用于定义输入和输出的数据类型。这些类型可以是对象,但也可以是原始值和数组。这个对象是 JSON Schema Specification Wright Draft 00 扩展后的子集.

关于property的的更多信息请查看 JSON Schema CoreJSON Schema Validation。除非另有说明,否则 properties 定义遵循JSON Schema。

Properties

以下 properties 是直接从 JSON Schema 提取出来的,而且遵循同样的规范:

  • title
  • multipleOf
  • maximum
  • exclusiveMaximum
  • minimum
  • exclusiveMinimum
  • maxLength
  • minLength
  • pattern (This string SHOULD be a valid regular expression, according to the ECMA 262 regular expression dialect)
  • maxItems
  • minItems
  • uniqueItems
  • maxProperties
  • minProperties
  • required
  • enum

以下 properties 是从 JSON Schema 提取出来的,但是做了一些调整以适应 OpenAPI Specification。

  • type - 值必须是一个字符串,不支持以数组形式定义多个值。
  • allOf - Inline 或 referenced 的 schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
  • oneOf - Inline 或 referenced 的 schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
  • anyOf - Inline 或 referenced 的 schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
  • not - Inline 或 referenced 的 schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
  • items - 值必须是一个对象且不是一个数组。Inline 或 referenced 的 schema 必须是一个 Schema 对象且不是一个标准的 JSON Schem。. items 必须存在如果 type 的值是 array
  • properties - Property 定义必须是一个 Schema 对象 且不是一个标准的 JSON Schema (inline 或 referenced).
  • additionalProperties - 值可以是 boolean 或 object. Inline 或 referenced schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
  • description - CommonMark syntax可以被用来呈现富文本格式.
  • format - 查看 Data Type Formats 以深入了解细节。在依靠 JSON Schema 定义的格式的同时,OAS 额外提供了一些预定义的格式。
  • default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. 不同于 JSON Schema,这个值必须符合定义与相同级别的 Schema 对象 中定义的类型,比如 typestring,那么 default 可以是 "foo" 但不能是 1

另外,任何可以使用 Schema 对象 的地方也可以使用 Reference 对象 替代。这允许引用一个定义而避免重复定义。

未在此处提及的 JSON Schema 规范中定义的其他属性将严格的不被支持。

Other than the JSON Schema subset fields, 以下字段可能会被用于后续的 schema documentation:

固定字段
字段名类型描述
nullableboolean对于定义的schema,允许发送 null 值。默认值是 false
discriminatorDiscriminator 对象Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See Composition and Inheritance for more details.
readOnlyboolean仅与 Schema "properties" 定义有关。 声明此属性是 "readonly" 的。这意味着它可以作为 response 的一部分但不应该作为 request 的一部分被发送。如果一个 property 的 readOnly 被标记为 true 且在 required 列表中,required 将只作用于 response。一个 property 的 readOnlywriteOnly 不允许同时被标记为 true。默认值是 false
writeOnlyboolean仅与 Schema "properties" 定义有关。声明此 property 为 "write only"。所以它可以作为 request 的一部分而不应该作为 response 的一部分被发送。如果一个 property 的 writeOnly 被标记为 true 且在 required 列表中,required 将只作用于 request。一个 property 的 readOnlywriteOnly 不能同时被标记为 true。默认值是 false
xmlXML 对象这只能用于 properties schemas,在 root schemas 中没有效果。Adds additional metadata to describe the XML representation of this property.
externalDocsExternal Documentation 对象此 schema 附加的外部文档。
exampleAny一个用于示范此 schema实例的示例,可以是任意格式。为了表达无法用 JSON 或 YAML 格式呈现的示例,可以使用 string 类型的值,且在必要的地方需要使用字符转义。
deprecatedboolean表示一个 schema 是废弃的,应该逐渐被放弃使用。默认值是 false.

这个对象可能会被规范扩展扩展。

Composition and Inheritance (Polymorphism)

The OpenAPI Specification allows combining and extending model definitions using the allOf property of JSON Schema, in effect offering model composition.allOf takes an array of object definitions that are validated independently but together compose a single object.

While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the discriminator field. When used, the discriminator will be the name of the property that decides which schema definition validates the structure of the model. As such, the discriminator field MUST be a required field. There are are two ways to define the value of a discriminator for an inheriting instance.

  • Use the schema name.
  • Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name.

As such, inline schema definitions, which do not have a given id, cannot be used in polymorphism.

XML Modeling

The xml property allows extra definitions when translating the JSON definition to XML. The XML 对象 contains additional information about the available options.

Schema 对象示例s
Primitive Sample
{
"type": "string",
"format": "email"
}
type: string
format: email
Simple Model
{
"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
Model with Map/Dictionary Properties

For a simple string to string mapping:

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

For a string to model mapping:

{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/ComplexModel"
}
}
type: object
additionalProperties:
$ref: '#/components/schemas/ComplexModel'
Model with Example
{
"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
Models with Composition
{
"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
Models with Polymorphism Support
{
"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

Discriminator 对象

当一个 request bodies 或 response payloads 可以是多种 schemas 时,可以使用一个 discriminator 对象来帮助序列化、反序列化和校验。 The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it.

当使用 discriminator 时,inline schemas 不会被考虑。

固定字段
字段名类型描述
propertyNamestring必选. 在 payload 中表示 discriminator 值的属性的名称。
mappingMap[string, string]一个映射 payload 中的值和 schema 名称或引用的对象。

discriminator 属性仅在与 oneOf, anyOf, allOf 这几个复合关键字之一一起使用时才合法.

在 OAS 3.0 中,一个 response payload 仅可以使用一种类型来描述:

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

也就是说 payload 必须 且只能满足 CatDogLizzard schemas 中的一个。 In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use:

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

The expectation now is that a property with name pet_type MUST be present in the response payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the response payload:

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

Will indicate that the Cat schema be used in conjunction with this payload.

In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional mapping definition MAY be used:

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: pet_type
mapping:
dog: '#/components/schemas/Dog'
monster: 'https://gigantic-server.com/schemas/Monster/schema.json'

Here the discriminator value of dog will map to the schema #/components/schemas/Dog, rather than the default (implicit) value of Dog. If the discriminator value does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison.

When used in conjunction with the anyOf construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload.

In both the oneOf and anyOf use cases, all possible schemas MUST be listed explicitly. To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas comprising the parent schema in an allOf construct may be used as an alternate schema.

For example:

components:
schemas:
Pet:
type: object
required:
- pet_type
properties:
pet_type:
type: string
discriminator:
propertyName: pet_type
mapping:
cachorro: 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

a payload like this:

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

will indicate that the Cat schema be used. Likewise this schema:

{
"pet_type": "cachorro",
"bark": "soft"
}

will map to Dog because of the definition in the mappings element.

XML 对象

一个为 XML 模型定义微调过的元数据对象。

当使用数组时,不会推测 XML 元素的名称(单数或复数形式),所以应该添加 name 属性来提供此信息。 查看展示此期望的示例。

固定字段
字段名类型描述
namestring替换用于描述元素/属性的结构特性的名称。当在 items 内定义时将会影响处于此列表中的每个元素的名称。当定义于 items 之上时将会影响它说包裹的元素且仅当 wrappedtrue 时,如果 wrappedfalse 时它将会被忽略。
namespacestring命名空间定义的 URI。其值必须是绝对 URI。
prefixstring用于 name 的前缀。
attributeboolean声明此特性定义会被转换为一个属性而不是一个元素。默认值是 false
wrappedboolean只可被用于数组定义。表示数组是否被包裹(比如, <books><book/><book/></books>)或未被包裹(<book/><book/>)。默认值是 false。此定义只在 typearray(位于 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>

Affecting both internal and external names:

{
"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>

Security Scheme 对象

定义一个用于 operations 的 security scheme。被支持的 schemes 有 HTTP 认证,一个 API key(作为 header 或 query parameter),定义于RFC6749 的 Oauth2 常用流程(implicit、password、application 和 access code)和 OpenID Connect Discovery

固定字段
字段名类型Applies To描述
typestringAny必选. security scheme 的类型。有效值包括 "apiKey", "http", "oauth2", "openIdConnect".
descriptionstringAny对 security scheme 的简短描述. CommonMark syntax可以被用来呈现富文本格式.
namestringapiKey必选. 用于 header、 query 或 cookie 的参数名字。
instringapiKey必选. API key 的位置。有效值包括 "query""header""cookie".
schemestringhttp必选. 用于 Authorization header as defined in RFC7235 的 HTTP Auahorization scheme 的名字.
bearerFormatstringhttp ("bearer")用于提示客户端所使用的bearer token的格式。Bearer token 通常通过一个authorization server生成,所以这个字段最主要的目的是用来记录这个信息。
flowsOAuth Flows 对象oauth2必选. 一个包含所支持的 flow types 的配置信息的对象。
openIdConnectUrlstringopenIdConnect必选. 用于发现 OAuth2 配置值的OpenId Connect URL,必须是 URL 形式。

这个对象可能会被规范扩展扩展。

Security Scheme 对象示例
Basic Authentication Sample
{
"type": "http",
"scheme": "basic"
}
type: http
scheme: basic
API Key Sample
{
"type": "apiKey",
"name": "api_key",
"in": "header"
}
type: apiKey
name: api_key
in: header
JWT Bearer Sample
{
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
}
type: http
scheme: bearer
bearerFormat: JWT
Implicit OAuth2 Sample
{
"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 Flows 对象

允许配置支持的 OAuth Flows。

固定字段
字段名类型描述
implicitOAuth Flow 对象OAuth Implicit flow 的配置
passwordOAuth Flow 对象OAuth Resource Owner Password flow 的配置
clientCredentialsOAuth Flow 对象OAuth Client Credentials flow 的配置。在 OpenAPI 2.0 中曾被称作 application
authorizationCodeOAuth Flow 对象OAuth Authorization Code flow 的配置。在 OpenAPI 2.0 中曾被称作 accessCode

这个对象可能会被规范扩展扩展。

OAuth Flow 对象

支持的 OAuth Flow 的配置详情。

固定字段
字段名类型Applies To描述
authorizationUrlstringoauth2 ("implicit", "authorizationCode")必选。用于此流程的 authorization URL。必须是 URL 形式。
tokenUrlstringoauth2 ("password", "clientCredentials", "authorizationCode")必选。用于此流程的 token URL。必须是 URL 形式。
refreshUrlstringoauth2用于获取 refresh tokens 的 URL,必须是 URL 形式。
scopesMap[string, string]oauth2必选。可用于 OAuth2 security scheme 的 scope。scope 名称与其简短描述的映射。

这个对象可能会被规范扩展扩展。

OAuth Flow 对象示例s
{
"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

Security Requirement 对象

列出执行此 operation 所需的 security schemes。每个属性的名字都必须与Components 对象Security Schemes 声明的 security scheme 相符。

包含多个 schemes 的 Security Requirement 对象中的所有 scheme 都必须要满足授权请求。这便能够支持需要使用多个 query parameters 或 HTTP headers 来传递安全信息的情景。

当When a list of Security Requirement Objects is defined on the Open API 对象 或 [Operation 对象] (#operationObject) 包含一组 Security Requirement 对象时,请求只需要满足其中一个即可。

模式字段
字段名模式类型描述
{name}[string]每个名称都必须对应于 Components 对象 下的 Security Schemes 的一个 security scheme。如果此 security scheme 是 "oauth2""openIdConnect" 类型,那么其值是用于执行的一组 scope names。对于其他 security scheme 类型。此数组必须是空的。
Security Requirement 对象示例
Non-OAuth2 Security Requirement
{
"api_key": []
}
api_key: []
OAuth2 Security Requirement
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
petstore_auth:
- write:pets
- read:pets

六、规范扩展

尽管 OpenAPI Specification 尝试包含大部分的使用场景,在需要时仍然可以通过附加数据来扩展此规范。

此扩展属性被设计为总是以 "x-" 为前缀的模式字段。

字段名模式类型描述
^x-Any允许扩展 OpenAPI Schema。此字段名必须以 x- 开头,比如 x-internal-id。此字段的值可以是 null、原始类型、数组或对象。可以包含任意有效的 JSON 格式的值。

此扩展可能会也可能不会被当前的工具支持,但是可以请求工具开发者支持此扩展(如果工具是内部或开源的)。

七、Security Filtering

Some objects in the OpenAPI Specification MAY be declared and remain empty, or be completely removed, even though they are inherently the core of the API documentation.

The reasoning is to allow an additional layer of access control over the documentation. While not part of the specification itself, certain libraries MAY choose to allow access to parts of the documentation based on some form of authentication/authorization.

Two examples of this:

  1. The Paths 对象 MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the Info 对象 which may contain additional information regarding authentication.
  2. The Path Item 对象 MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different than hiding the path itself from the Paths 对象, so the user will not be aware of its existence. This allows the documentation provider to finely control what the viewer can see.

八、Appendix A: Revision History

VersionDateNotes
3.0.02017-07-26Release of the OpenAPI Specification 3.0.0
3.0.0-rc22017-06-16rc2 of the 3.0 specification
3.0.0-rc12017-04-27rc1 of the 3.0 specification
3.0.0-rc02017-02-28Implementer's Draft of the 3.0 specification
2.02015-12-31Donation of Swagger 2.0 to the Open API Initiative
2.02014-09-08Release of Swagger 2.0
1.22014-03-14Initial release of the formal document.
1.12012-08-22Release of Swagger 1.1
1.02011-08-10First release of the Swagger Specification