OpenAPI 规范 v3.0.1

版本 3.0.1

关于此文档的更多详细信息
此版本
https://spec.openapis.org.cn/oas/v3.0.1.html
最新发布版本
https://spec.openapis.org.cn/oas/latest.html
最新编辑草稿
https://github.com/OAI/OpenAPI-Specification/
编辑
Darrel Miller
Jeremy Whitlock
Marsh Gardiner
Ron Ratovsky
前任编辑
Jason Harmon
Tony Tam
参与
GitHub OAI/OpenAPI-Specification
提交错误
提交历史
拉取请求

什么是 OpenAPI 规范?

OpenAPI 规范 (OAS) 定义了一种标准的、与编程语言无关的 HTTP API 接口描述,它允许人类和计算机在无需访问源代码、其他文档或检查网络流量的情况下发现和理解服务的的功能。当通过 OpenAPI 正确定义时,使用者可以使用最少的实现逻辑来理解和与远程服务进行交互。类似于接口描述对较低级别编程所做的工作,OpenAPI 规范消除了调用服务的猜测工作。

本文档的状态

此规范的真相来源是上面引用的 HTML 文件,称为“此版本”。

1. OpenAPI 规范

1.1 版本 3.0.1

本文档中的关键词“必须”、“禁止”、“必需”、“”、“不应”、“应该”、“不应该”、“推荐”、“不推荐”、“可以”和“可选”应按BCP 14 [RFC2119] [RFC8174] 中所述进行解释,仅当它们以全部大写形式出现时,如本文所示。

本文档根据Apache 许可证 2.0 版获得许可。

2. 简介

OpenAPI 规范 (OAS) 定义了一个标准的、与语言无关的 RESTful API 接口,它允许人类和计算机在无需访问源代码、文档或通过网络流量检查的情况下发现和理解服务的的功能。当正确定义时,使用者可以使用最少的实现逻辑来理解和与远程服务进行交互。

然后,OpenAPI 定义可被文档生成工具用于显示 API,代码生成工具用于以各种编程语言生成服务器和客户端,测试工具以及许多其他用例。

3. 定义

3.1 OpenAPI 文档

定义或描述 API 的文档(或一组文档)。OpenAPI 定义使用并符合 OpenAPI 规范。

3.2 路径模板

路径模板是指使用花括号 ({}) 将 URL 路径的一部分标记为可使用路径参数替换。

3.3 媒体类型

媒体类型定义分散在多个资源中。媒体类型定义应该符合 [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] 第 6 节 定义,已注册的状态码列在IANA 状态码注册表中。

4. 规范

4.1 版本

OpenAPI 规范使用语义版本控制 2.0.0 (semver) 进行版本控制,并遵循 semver 规范。

semver 的 major.minor 部分(例如 3.0指定 OAS 功能集。通常,.patch 版本解决此文档中的错误,而不是功能集。支持 OAS 3.0 的工具应该与所有 OAS 3.0.* 版本兼容。工具不考虑修订版本,例如,不区分 3.0.03.0.1

OpenAPI 规范的后续次要版本发布(递增 minor 版本号)不应干扰为较低次要版本和相同主要版本开发的工具。因此,假设的 3.1.0 规范应该可用于为 3.0.0 设计的工具。

一个与 OAS 3.*.* 兼容的 OpenAPI 文档包含一个必需的 openapi 字段,该字段指定其使用的 OAS 的语义版本。(OAS 2.0 文档包含一个名为 swagger 且值为 "2.0" 的顶级版本字段。)

4.2 格式

符合 OpenAPI 规范的 OpenAPI 文档本身就是一个 JSON 对象,可以以 JSONYAML 格式表示。

例如,如果一个字段具有数组值,则将使用 JSON 数组表示形式

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

规范中的所有字段名称都区分大小写

该模式公开了两种类型的字段:固定字段,具有声明的名称;模式字段,为字段名称声明正则表达式模式。

模式字段必须在包含的对象中具有唯一的名称。

为了保留在 YAML 和 JSON 格式之间进行双向转换的能力,YAML 1.2 版本 建议与一些额外的约束一起使用。

注意:虽然 API 可以通过 YAML 或 JSON 格式的 OpenAPI 文档来定义,但 API 请求和响应主体以及其他内容不需要是 JSON 或 YAML。

4.3 文档结构

一个 OpenAPI 文档可以由单个文档组成,也可以根据用户的意愿分成多个相互关联的部分。在后一种情况下,必须在规范中使用 $ref 字段来引用这些部分,如下面的 JSON Schema 定义所示。

建议将根 OpenAPI 文档命名为:openapi.jsonopenapi.yaml

4.4 数据类型

OAS 中的原始数据类型基于 JSON Schema 规范 Wright 草案 00 支持的类型。请注意,integer 作为一种类型也受支持,并定义为没有小数或指数部分的 JSON 数字。null 不支持作为类型(有关替代解决方案,请参阅 nullable)。模型使用 Schema 对象 定义,它是 JSON Schema 规范 Wright 草案 00 的扩展子集。

基元具有一个可选的修饰符属性:format。OAS 使用几种已知的格式来详细定义正在使用的的数据类型。但是,为了支持文档需求,format 属性是一个开放的 string 值属性,可以具有任何值。即使此规范未定义,也可以使用诸如 "email""uuid" 等格式。可以使用。没有 format 属性的类型遵循 JSON Schema 中的类型定义。无法识别特定 format 的工具可以默认回退到仅使用 type,就像未指定 format 一样。

OAS 定义的格式为

通用名称 类型 格式 注释
整数 整数 int32 有符号 32 位
长整数 整数 int64 有符号 64 位
浮点数 数字 浮点数
双精度浮点数 数字 双精度浮点数
字符串 字符串
字节 字符串 字节 base64 编码字符
二进制 字符串 二进制 任何字节序列
布尔值 布尔值
日期 字符串 日期 full-date 所定义 - [RFC3339] 第 5.6 节
日期时间 字符串 date-time date-time 所定义 - [RFC3339] 第 5.6 节
密码 字符串 密码 提示 UI 隐藏输入。

4.5 富文本格式化

在整个规范中,description 字段都被注释为支持 [CommonMark] markdown 格式。在 OpenAPI 工具渲染富文本时,必须至少支持 [CommonMark-0.27] 中描述的 markdown 语法。工具可以选择忽略某些 CommonMark 功能以解决安全问题。

4.6 URL 中的相对引用

除非另有说明,否则所有作为 URL 的属性可以是 [RFC3986] 第 4.2 节 中定义的相对引用。使用 Server 对象 中定义的 URL 作为基本 URI 来解析相对引用。

$ref 中使用的相对引用根据 JSON 引用 进行处理,使用当前文档的 URL 作为基本 URI。另请参阅 引用对象

4.7 模式

在下述说明中,如果某个字段未明确必需或未描述为 必须应该,则可以将其视为 可选

4.7.1 OpenAPI 对象

这是 OpenAPI 文档 的根文档对象。

4.7.1.1 固定字段
字段名称 类型 描述
openapi 字符串 必需。此字符串必须是 OpenAPI 文档使用的 语义版本号openapi 字段应该由工具规范和客户端用来解释 OpenAPI 文档。这与 API info.version 字符串无关
info 信息对象 必需。提供有关 API 的元数据。元数据可以根据需要由工具使用。
servers [服务器对象] 服务器对象的数组,提供到目标服务器的连接信息。如果未提供 servers 属性或该属性为空数组,则默认值为 服务器对象,其 url 值为 /
paths 路径对象 必需。API 可用的路径和操作。
components 组件对象 用于保存规范中各种模式的元素。
security [安全需求对象] 跨 API 可使用哪些安全机制的声明。值的列表包括可使用的替代安全需求对象。只需满足安全需求对象之一即可授权请求。各个操作可以覆盖此定义。
tags [标签对象] 规范使用的标签列表,以及其他元数据。标签的顺序可用于反映解析工具对其的顺序。并非 操作对象 使用的所有标签都必须声明。未声明的标签可以随机组织或基于工具的逻辑组织。列表中的每个标签名称必须唯一。
externalDocs 外部文档对象 其他外部文档。

此对象可以使用 规范扩展 进行扩展。

4.7.2 Info 对象

该对象提供有关 API 的元数据。如果需要,客户端可以使用元数据,并且为了方便起见,可以在编辑或文档生成工具中呈现元数据。

4.7.2.1 固定字段
字段名称 类型 描述
title 字符串 必需。应用程序的标题。
description 字符串 应用程序的简短描述。[CommonMark] 语法可以用于富文本表示。
termsOfService 字符串 API 的服务条款的 URL。必须采用 URL 格式。
contact 联系对象 公开 API 的联系信息。
license 许可证对象 公开 API 的许可证信息。
version 字符串 必需。OpenAPI 文档的版本(与 OpenAPI 规范版本 或 API 实现版本不同)。

此对象可以使用 规范扩展 进行扩展。

4.7.2.2 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": "[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

4.7.3 Contact 对象

公开 API 的联系信息。

4.7.3.1 固定字段
字段名称 类型 描述
name 字符串 联系人/组织的识别名称。
url 字符串 指向联系信息的 URL。必须采用 URL 格式。
email 字符串 联系人/组织的电子邮件地址。必须采用电子邮件地址格式。

此对象可以使用 规范扩展 进行扩展。

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

4.7.4 License 对象

公开 API 的许可证信息。

4.7.4.1 固定字段
字段名称 类型 描述
name 字符串 必需。API 使用的许可证名称。
url 字符串 API 使用的许可证的 URL。必须采用 URL 格式。

此对象可以使用 规范扩展 进行扩展。

4.7.4.2 License 对象示例
{
  "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

4.7.5 Server 对象

表示服务器的对象。

4.7.5.1 固定字段
字段名称 类型 描述
url 字符串 必需。目标主机的 URL。此 URL 支持服务器变量,并且可以是相对的,以指示主机位置相对于提供 OpenAPI 文档的位置。当在 {括号} 中命名变量时,将进行变量替换。
description 字符串 描述 URL 指定的主机的可选字符串。[CommonMark] 语法可以用于富文本表示。
variables Map[string, 服务器变量对象] 变量名称与其值之间的映射。该值用于替换服务器的 URL 模板。

此对象可以使用 规范扩展 进行扩展。

4.7.5.2 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

4.7.6 Server Variable 对象

表示服务器 URL 模板替换的服务器变量的对象。

4.7.6.1 固定字段
字段名称 类型 描述
enum [string] 如果替换选项来自有限集,则要使用的字符串值的枚举。
default 字符串 必需。用于替换的默认值,如果未提供备选值,则发送该默认值。与Schema 对象default不同,此值必须由消费者提供。
描述 字符串 服务器变量的可选描述。[CommonMark] 语法可以用于富文本表示。

此对象可以使用 规范扩展 进行扩展。

4.7.7 Components 对象

包含一组可重用的对象,用于 OAS 的不同方面。组件对象中定义的所有对象都不会对 API 产生影响,除非它们是从组件对象外部的属性中明确引用的。

4.7.7.1 固定字段
字段名称 类型 描述
模式 Map[string, Schema 对象 | 引用对象] 一个对象,用于保存可重用的Schema 对象
响应 Map[string, 响应对象 | 引用对象] 一个对象,用于保存可重用的响应对象
参数 Map[string, 参数对象 | 引用对象] 一个对象,用于保存可重用的参数对象
示例 Map[string, 示例对象 | 引用对象] 一个对象,用于保存可重用的示例对象
请求体 Map[string, 请求体对象 | 引用对象] 一个对象,用于保存可重用的请求体对象
头部 Map[string, 头部对象 | 引用对象] 一个对象,用于保存可重用的头部对象
安全方案 Map[string, 安全方案对象 | 引用对象] 一个对象,用于保存可重用的安全方案对象
链接 Map[string, 链接对象 | 引用对象] 一个对象,用于保存可重用的链接对象
回调 Map[string, 回调对象 | 引用对象] 一个对象,用于保存可重用的回调对象

此对象可以使用 规范扩展 进行扩展。

上面声明的所有固定字段都是必须使用与正则表达式匹配的键的对象:^[a-zA-Z0-9\.\-_]+$

字段名称示例

User
User_1
User_Name
user-name
my.org.User
4.7.7.2 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

4.7.8 Paths 对象

包含到各个端点及其操作的相对路径。路径附加到服务器对象的 URL 以构建完整 URL。由于ACL 约束,路径可以为空。

4.7.8.1 模式化字段
字段模式 类型 描述
/{path} 路径项对象 到单个端点的相对路径。字段名称必须以斜杠开头。路径附加(没有相对 URL 解析)到服务器对象url字段中的扩展 URL 以构建完整 URL。路径模板是允许的。在匹配 URL 时,具体(非模板化)路径将在其模板化对应部分之前匹配。具有相同层次结构但模板名称不同的模板化路径不得存在,因为它们是相同的。如果存在模糊匹配,则由工具决定使用哪一个。

此对象可以使用 规范扩展 进行扩展。

4.7.8.2 路径模板匹配

假设以下路径,如果使用具体定义/pets/mine,将首先匹配。

  /pets/{petId}
  /pets/mine

以下路径被认为是相同的且无效的

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

以下可能导致模糊解析

  /{entity}/me
  /books/{id}
4.7.8.3 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'

4.7.9 Path Item 对象

描述单个路径上可用的操作。由于ACL 约束,路径项可以为空。路径本身仍然会显示给文档查看器,但他们将不知道哪些操作和参数可用。

4.7.9.1 固定字段
字段名称 类型 描述
$ref 字符串 允许外部定义此路径项。引用的结构必须采用路径项对象的格式。如果引用的定义与此路径项的定义之间存在冲突,则行为未定义
摘要 字符串 一个可选的字符串摘要,旨在应用于此路径中的所有操作。
描述 字符串 一个可选的字符串描述,旨在应用于此路径中的所有操作。[CommonMark] 语法可以用于富文本表示。
get 操作对象 此路径上 GET 操作的定义。
put 操作对象 此路径上 PUT 操作的定义。
post 操作对象 此路径上 POST 操作的定义。
delete 操作对象 此路径上 DELETE 操作的定义。
options 操作对象 此路径上 OPTIONS 操作的定义。
head 操作对象 此路径上 HEAD 操作的定义。
patch 操作对象 此路径上 PATCH 操作的定义。
trace 操作对象 此路径上 TRACE 操作的定义。
服务器 [服务器对象] 此路径中所有操作的服务的替代server数组。
参数 [参数对象 | 引用对象] 适用于此路径下描述的所有操作的参数列表。这些参数可以在操作级别覆盖,但不能在那里删除。列表不得包含重复的参数。唯一参数由名称位置的组合定义。该列表可以使用引用对象链接到OpenAPI 对象的 components/parameters中定义的参数。

此对象可以使用 规范扩展 进行扩展。

4.7.9.2 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 

4.7.10 Operation 对象

描述路径上的单个 API 操作。

4.7.10.1 固定字段
字段名称 类型 描述
标签 [string] 用于 API 文档控制的一组标签。标签可用于根据资源或任何其他限定符对操作进行逻辑分组。
摘要 字符串 操作执行内容的简短摘要。
描述 字符串 操作行为的详细说明。[CommonMark] 语法可以用于富文本表示。
外部文档 外部文档对象 此操作的其他外部文档。
操作ID 字符串 用于标识操作的唯一字符串。ID必须在 API 中描述的所有操作中唯一。工具和库可以使用 operationId 唯一地标识操作,因此,建议遵循常见的编程命名约定。
参数 [参数对象 | 引用对象] 适用于此操作的参数列表。如果参数已在路径项中定义,则新定义将覆盖它,但永远不会删除它。列表不得包含重复的参数。唯一参数由名称位置的组合定义。该列表可以使用引用对象链接到OpenAPI 对象的 components/parameters中定义的参数。
请求体 请求体对象 | 引用对象 适用于此操作的请求体。requestBody仅支持 HTTP 方法,其中 HTTP 1.1 规范[RFC7231] 第 4.3.1 节已明确定义了请求体的语义。在 HTTP 规范含糊不清的其他情况下,消费者忽略requestBody
响应 响应对象 必需。执行此操作返回的可能响应列表。
回调 Map[string, 回调对象 | 引用对象] 与父操作相关的可能带外回调的映射。键是回调对象的唯一标识符。映射中的每个值都是一个回调对象,它描述了 API 提供者可能发起的请求以及预期的响应。用于标识回调对象的键值是一个在运行时计算的表达式,该表达式标识要用于回调操作的 URL。
已弃用 布尔值 声明此操作已弃用。消费者应该避免使用声明的操作。默认值为false
安全 [安全需求对象] 声明可用于此操作的安全机制。值列表包含可使用的替代安全需求对象。只需要满足安全需求对象之一即可授权请求。此定义覆盖任何声明的顶级security。要删除顶级安全声明,可以使用空数组。
服务器 [服务器对象] 此操作的服务的替代server数组。如果在路径项对象或根级别指定了替代server对象,则此值将覆盖它。

此对象可以使用 规范扩展 进行扩展。

4.7.10.2 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

4.7.11 External Documentation 对象

允许引用外部资源以获取扩展文档。

4.7.11.1 固定字段
字段名称 类型 描述
描述 字符串 目标文档的简短描述。[CommonMark] 语法可以用于富文本表示。
URL 字符串 必需。目标文档的 URL。值必须采用 URL 格式。

此对象可以使用 规范扩展 进行扩展。

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

4.7.12 Parameter 对象

描述单个操作参数。

唯一参数由名称位置的组合定义。

4.7.12.1 参数位置

in字段指定了四个可能的参数位置

  • path - 与路径模板一起使用,其中参数值实际上是操作 URL 的一部分。这并不包括 API 的主机或基本路径。例如,在/items/{itemId}中,路径参数为itemId
  • query - 附加到 URL 的参数。例如,在/items?id=###中,查询参数为id
  • header - 预期作为请求一部分的自定义头部。请注意,[RFC7230] 第 22 页指出头部名称不区分大小写。
  • cookie - 用于将特定 cookie 值传递给 API。
4.7.12.2 固定字段
字段名称 类型 描述
名称 字符串 必需。参数的名称。参数名称区分大小写
  • 如果 in"path",则 name 字段必须对应于来自 path 字段中 路径对象 的关联路径段。有关更多信息,请参阅 路径模板
  • 如果 in"header"name 字段为 "Accept""Content-Type""Authorization",则参数定义应该被忽略。
  • 对于所有其他情况,name 对应于 in 属性使用的参数名称。
in 字符串 必需。参数的位置。可能的值为“query”、“header”、“path”或“cookie”。
description 字符串 参数的简要描述。这可能包含使用示例。[CommonMark] 语法可以用于富文本表示。
required 布尔值 确定此参数是否为必填。如果 参数位置 为“path”,则此属性为必需,其值必须true。否则,可以包含该属性,其默认值为 false
deprecated 布尔值 指定参数已弃用,应该停止使用。
allowEmptyValue 布尔值 设置传递空值参数的能力。这仅对 query 参数有效,并允许发送具有空值的参数。默认值为 false。如果使用 style,并且如果行为为 n/a(无法序列化),则应该忽略 allowEmptyValue 的值。

参数序列化的规则以两种方式之一指定。对于更简单的场景,schemastyle 可以描述参数的结构和语法。

字段名称 类型 描述
style 字符串 根据参数值的类型描述参数值将如何序列化。默认值(基于 in 的值):对于 query - form;对于 path - simple;对于 header - simple;对于 cookie - form
explode 布尔值 当此值为 true 时,类型为 arrayobject 的参数值会为数组的每个值或映射的键值对生成单独的参数。对于其他类型的参数,此属性无效。当 styleform 时,默认值为 true。对于所有其他样式,默认值为 false
allowReserved 布尔值 确定参数值应该允许保留字符,如 [RFC3986] 第 2.2 节 :/?#[]@!$&'()*+,;= 是否包含在内,而无需进行百分比编码。此属性仅适用于 in 值为 query 的参数。默认值为 false
schema Schema 对象 | 引用对象 定义用于参数的类型的模式。
example 任何 媒体类型的示例。如果存在,示例应该与指定的模式和编码属性匹配。example 字段与 examples 字段互斥。此外,如果引用包含示例的 schema,则 example必须覆盖模式提供的示例。为了表示无法以 JSON 或 YAML 自然表示的媒体类型的示例,字符串值可以包含示例,并在必要时进行转义。
examples Map[ string, 示例对象 | 引用对象] 媒体类型的示例。每个示例应该包含以参数编码中指定的正确格式的值。examples 字段与 example 字段互斥。此外,如果引用包含示例的 schema,则 examples必须覆盖模式提供的示例。

对于更复杂的场景,content 属性可以定义参数的媒体类型和模式。参数必须包含 schema 属性或 content 属性,但不能同时包含两者。当 exampleexamplesschema 对象一起提供时,示例必须遵循参数规定的序列化策略。

字段名称 类型 描述
content Map[string, 媒体类型对象] 包含参数表示形式的映射。键是媒体类型,值描述它。映射必须仅包含一个条目。
4.7.12.3 样式值

为了支持序列化简单参数的常用方法,定义了一组 style 值。

style 类型 in 注释
matrix primitivearrayobject path [RFC6570] 第 3.2.7 节 定义的路径样式参数
label primitivearrayobject path [RFC6570] 第 3.2.5 节 定义的标签样式参数
form primitivearrayobject querycookie [RFC6570] 第 3.2.8 节 定义的表单样式参数。此选项用 OpenAPI 2.0 中的 csv(当 explode 为 false 时)或 multi(当 explode 为 true 时)值替换 collectionFormat
simple array pathheader [RFC6570] 第 3.2.2 节 定义的简单样式参数。此选项用 OpenAPI 2.0 中的 csv 值替换 collectionFormat
spaceDelimited array query 以空格分隔的数组值。此选项替换 OpenAPI 2.0 中等于 ssvcollectionFormat
pipeDelimited array query 以管道分隔的数组值。此选项替换 OpenAPI 2.0 中等于 pipescollectionFormat
deepObject object query 提供了一种使用表单参数渲染嵌套对象简单的方法。
4.7.12.4 样式示例

假设名为 color 的参数具有以下值之一

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

下表显示了每个值的渲染差异示例。

style explode empty 字符串 array object
matrix false ;color ;color=blue ;color=blue,black,brown ;color=R,100,G,200,B,150
matrix true ;color ;color=blue ;color=blue;color=black;color=brown ;R=100;G=200;B=150
label false . .blue .blue.black.brown .R.100.G.200.B.150
label true . .blue .blue.black.brown .R=100.G=200.B=150
form false color= color=blue color=blue,black,brown color=R,100,G,200,B,150
form true color= color=blue color=blue&color=black&color=brown R=100&G=200&B=150
simple false n/a blue blue,black,brown R,100,G,200,B,150
simple true n/a blue blue,black,brown R=100,G=200,B=150
spaceDelimited false n/a n/a blue%20black%20brown R%20100%20G%20200%20B%20150
pipeDelimited false n/a n/a blue|black|brown R|100|G|200
deepObject true n/a n/a n/a color[R]=100&color[G]=200&color[B]=150

此对象可以使用 规范扩展 进行扩展。

4.7.12.5 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

4.7.13 Request Body 对象

描述单个请求正文。

4.7.13.1 固定字段
字段名称 类型 描述
description 字符串 请求正文的简要描述。这可能包含使用示例。[CommonMark] 语法可以用于富文本表示。
content Map[string, 媒体类型对象] 必需。请求正文的内容。键是媒体类型或媒体类型范围,请参阅 [RFC7231] 附录 D,值描述它。对于匹配多个键的请求,仅适用最具体的键。例如,text/plain 覆盖 text/*
required 布尔值 确定请求中是否需要请求正文。默认为 false

此对象可以使用 规范扩展 进行扩展。

4.7.13.2 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

4.7.14 Media Type 对象

每个媒体类型对象都为其键标识的媒体类型提供模式和示例。

4.7.14.1 固定字段
字段名称 类型 描述
schema Schema 对象 | 引用对象 定义用于请求正文的类型的模式。
example 任何 媒体类型的示例。示例对象应该以媒体类型指定的正确格式显示。example 字段与 examples 字段互斥。此外,如果引用包含示例的 schema,则 example必须覆盖模式提供的示例。
examples Map[ string, 示例对象 | 引用对象] 媒体类型的示例。每个示例对象应该与媒体类型和指定的模式(如果存在)匹配。examples 字段与 example 字段互斥。此外,如果引用包含示例的 schema,则 examples必须覆盖模式提供的示例。
encoding Map[string, 编码对象] 属性名称与其编码信息之间的映射。键(即属性名称)必须在模式中作为属性存在。编码对象应该仅在媒体类型为 multipartapplication/x-www-form-urlencoded 时应用于 requestBody 对象。

此对象可以使用 规范扩展 进行扩展。

4.7.14.2 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"
4.7.14.3 文件上传的注意事项

与 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:
      # 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

4.7.14.4 对 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

4.7.14.5 multipart 内容的特殊注意事项

在将请求正文传输到操作时,通常使用 multipart/form-data 作为 Content-Type。与 2.0 相比,当使用 multipart 内容时,必须使用 schema 来定义操作的输入参数。这支持复杂结构以及支持多种文件上传的机制。

在传入 multipart 类型时,可以使用边界来分隔正在传输的内容部分——因此,为 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'

引入了一个 encoding 属性,用于控制 multipart 请求体部分的序列化。此属性**仅**适用于 multipartapplication/x-www-form-urlencoded 请求体。

4.7.15 Encoding 对象

应用于单个架构属性的单个编码定义。

4.7.15.1 固定字段
字段名称 类型 描述
contentType 字符串 编码特定属性的 Content-Type。默认值取决于属性类型:对于 formatbinarystring 类型 - application/octet-stream;对于其他基本类型 - text/plain;对于 object 类型 - application/json;对于 array 类型 - 默认值基于内部类型定义。该值可以是特定的媒体类型(例如 application/json),通配符媒体类型(例如 image/*)或两种类型的逗号分隔列表。
headers Map[string, 头部对象 | 引用对象] 一个映射,允许提供其他信息作为标头,例如 Content-DispositionContent-Type 在单独描述,并且在此部分**必须**被忽略。如果请求体媒体类型不是 multipart,则此属性**必须**被忽略。
style 字符串 根据属性类型描述特定属性值将如何序列化。有关 style 属性的详细信息,请参阅参数对象。行为遵循与 query 参数相同的取值,包括默认值。如果请求体媒体类型不是 application/x-www-form-urlencoded,则此属性**必须**被忽略。
explode 布尔值 如果此值为 true,则 arrayobject 类型的属性值会为数组的每个值或映射的每个键值对生成单独的参数。对于其他类型的属性,此属性无效。当 styleform 时,默认值为 true。对于所有其他样式,默认值为 false。如果请求体媒体类型不是 application/x-www-form-urlencoded,则此属性**必须**被忽略。
allowReserved 布尔值 确定参数值**应该**允许包含哪些保留字符,如 [RFC3986] 第 2.2 节 定义的 :/?#[]@!$&'()*+,;=,而无需进行百分比编码。默认值为 false。如果请求体媒体类型不是 application/x-www-form-urlencoded,则此属性**必须**被忽略。

此对象可以使用 规范扩展 进行扩展。

4.7.15.2 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

4.7.16 Responses 对象

操作预期响应的容器。该容器将 HTTP 响应代码映射到预期的响应。

文档不一定需要涵盖所有可能的 HTTP 响应代码,因为它们可能事先未知。但是,文档需要涵盖成功的操作响应和任何已知的错误。

default **可以**用作所有未由规范单独涵盖的 HTTP 代码的默认响应对象。

响应对象**必须**包含至少一个响应代码,并且**应该**是成功操作调用的响应。

4.7.16.1 固定字段
字段名称 类型 描述
default 响应对象 | 引用对象 除了为特定 HTTP 响应代码声明的响应之外的响应文档。使用此字段来涵盖未声明的响应。一个 引用对象 可以链接到 OpenAPI 对象的 components/responses 部分定义的响应。
4.7.16.2 模式化字段
字段模式 类型 描述
HTTP 状态代码 响应对象 | 引用对象 任何 HTTP 状态代码 都可以用作属性名称,但每个代码只有一个属性,用于描述该 HTTP 状态代码的预期响应。一个 引用对象 可以链接到 OpenAPI 对象的 components/responses 部分中定义的响应。为了在 JSON 和 YAML 之间保持兼容性,此字段**必须**用引号括起来(例如,“200”)。要定义响应代码范围,此字段**可以**包含大写通配符 X。例如,2XX 表示 [200-299] 之间的所有响应代码。允许以下范围定义:1XX2XX3XX4XX5XX。如果使用显式代码定义了响应范围,则该代码的显式代码定义优先于范围定义。

此对象可以使用 规范扩展 进行扩展。

4.7.16.3 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'

4.7.17 Response 对象

描述来自 API 操作的单个响应,包括基于响应的操作的设计时静态 links

4.7.17.1 固定字段
字段名称 类型 描述
description 字符串 必需。响应的简短描述。[CommonMark] 语法**可以**用于富文本表示。
headers Map[string, 头部对象 | 引用对象] 将标头名称映射到其定义。[RFC7230] 第 22 页 指出标头名称不区分大小写。如果使用名称 "Content-Type" 定义了响应标头,则**必须**忽略它。
content Map[string, 媒体类型对象] 包含潜在响应有效负载描述的映射。键是媒体类型或媒体类型范围,请参阅 [RFC7231] 附录 D,值对其进行描述。对于与多个键匹配的响应,仅适用最具体的键。例如,text/plain 覆盖 text/*
links Map[string, 链接对象 | 引用对象] 可以从响应中遵循的操作链接的映射。映射的键是链接的简称,遵循 组件对象 名称的命名约束。

此对象可以使用 规范扩展 进行扩展。

4.7.17.2 Response 对象示例

复杂类型数组的响应

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

4.7.18 Callback 对象

与父操作相关的可能带外回调的映射。映射中的每个值都是一个 路径项对象,它描述了一组可能由 API 提供者发起的请求和预期的响应。用于标识回调对象的键值是一个在运行时计算的表达式,该表达式标识要用于回调操作的 URL。

4.7.18.1 模式化字段
字段模式 类型 描述
{expression} 路径项对象 用于定义回调请求和预期响应的路径项对象。可以访问完整的示例

此对象可以使用 规范扩展 进行扩展。

4.7.18.2 键表达式

标识 路径项对象 的键是一个 运行时表达式,可以在运行时 HTTP 请求/响应的上下文中进行计算,以标识要用于回调请求的 URL。一个简单的示例可能是 $request.body#/url。但是,使用 运行时表达式 可以访问完整的 HTTP 消息。这包括访问 JSON 指针 [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/stillrunning
$request.body#/successUrls/2 http://clientdomain.com/medium
$response.header.Location http://example.org/subscription/1
4.7.18.3 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

4.7.19 Example 对象

4.7.19.1 固定字段
字段名称 类型 描述
summary 字符串 示例的简短描述。
description 字符串 示例的详细描述。[CommonMark] 语法**可以**用于富文本表示。
value 任何 嵌入的文字示例。value 字段和 externalValue 字段是互斥的。要表示 JSON 或 YAML 中无法自然表示的媒体类型的示例,请使用字符串值包含示例,并在必要时进行转义。
externalValue 字符串 指向文字示例的 URL。这提供了引用 JSON 或 YAML 文档中难以包含的示例的功能。value 字段和 externalValue 字段是互斥的。

此对象可以使用 规范扩展 进行扩展。

在所有情况下,示例值都应与其关联值的类型架构兼容。工具实现**可以**选择自动验证兼容性,并在不兼容时拒绝示例值。

4.7.19.2 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'

4.7.21 Header 对象

头对象遵循参数对象的结构,并进行以下更改

  1. name不得指定,它在相应的headers映射中给出。
  2. in不得指定,它隐式地在header中。
  3. 受位置影响的所有特征必须适用于header的位置(例如,style)。
4.7.21.1 Header 对象示例

类型为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

4.7.22 Tag 对象

向由操作对象使用的单个标签添加元数据。对于操作对象实例中定义的每个标签,不必具有一个标签对象。

4.7.22.1 固定字段
字段名称 类型 描述
名称 字符串 必需。标签的名称。
描述 字符串 标签的简短描述。[CommonMark规范] 语法可以用于富文本表示。
外部文档 外部文档对象 此标签的其他外部文档。

此对象可以使用 规范扩展 进行扩展。

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

4.7.23 Reference 对象

一个简单的对象,允许引用规范中的其他组件,包括内部和外部。

引用对象由JSON 引用定义,并遵循相同的结构、行为和规则。

对于此规范,引用解析按照 JSON 引用规范定义的方式完成,而不是按照 JSON Schema 规范定义的方式完成。

4.7.23.1 固定字段
字段名称 类型 描述
$ref 字符串 必需。引用字符串。

此对象不能扩展其他属性,并且添加的任何属性都应被忽略。

4.7.23.2 Reference 对象示例
{
	"$ref": "#/components/schemas/Pet"
}
$ref: '#/components/schemas/Pet'
4.7.23.3 相对模式文档示例
{
  "$ref": "Pet.json"
}
$ref: Pet.yaml
4.7.23.4 包含嵌入式模式的相对文档示例
{
  "$ref": "definitions.json#/Pet"
}
$ref: definitions.yaml#/Pet

4.7.24 Schema 对象

Schema 对象允许定义输入和输出数据类型。这些类型可以是对象,也可以是基本类型和数组。此对象是JSON Schema 规范 Wright 草稿 00的扩展子集。

有关属性的更多信息,请参阅JSON Schema CoreJSON Schema Validation。除非另有说明,否则属性定义遵循 JSON Schema。

4.7.24.1 属性

以下属性直接取自 JSON Schema 定义,并遵循相同的规范

  • 标题
  • multipleOf
  • 最大值
  • exclusiveMaximum
  • 最小值
  • exclusiveMinimum
  • maxLength
  • minLength
  • 模式(此字符串为有效的正则表达式,根据ECMA 262 正则表达式方言)
  • maxItems
  • minItems
  • uniqueItems
  • maxProperties
  • minProperties
  • 必需
  • 枚举

以下属性取自 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。如果typearray,则必须存在items
  • properties - 属性定义必须Schema 对象,而不是标准 JSON Schema(内联或引用)。
  • additionalProperties - 值可以是布尔值或对象。内联或引用的 schema必须Schema 对象,而不是标准 JSON Schema。
  • description - [CommonMark规范] 语法可以用于富文本表示。
  • format - 有关更多详细信息,请参阅数据类型格式。虽然依赖于 JSON Schema 定义的格式,但 OAS 提供了一些其他预定义格式。
  • default - 默认值表示如果未提供输入值,则输入的使用者将假设为 schema 的值。与 JSON Schema 不同,该值必须符合在同一级别定义的 Schema 对象的定义类型。例如,如果typestring,则default可以为"foo",但不能为1

或者,在可以使用 Schema 对象的任何时候,都可以使用引用对象代替它。这允许引用定义而不是内联定义它们。

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

除了 JSON Schema 子集字段之外,以下字段可以用于进一步的 schema 文档

4.7.24.2 固定字段
字段名称 类型 描述
nullable 布尔值 允许为定义的 schema 发送null值。默认值为false
鉴别器 鉴别器对象 添加对多态性的支持。鉴别器是一个对象名称,用于区分可能满足有效负载描述的其他 schema。有关更多详细信息,请参阅组合和继承
readOnly 布尔值 仅与 Schema "properties"定义相关。将属性声明为“只读”。这意味着它可以作为响应的一部分发送,但不应作为请求的一部分发送。如果属性被标记为readOnlytrue并且在required列表中,则required将仅对响应生效。属性不得同时标记为readOnlywriteOnlytrue。默认值为false
writeOnly 布尔值 仅与 Schema "properties"定义相关。将属性声明为“只写”。因此,它可以作为请求的一部分发送,但不应作为响应的一部分发送。如果属性被标记为writeOnlytrue并且在required列表中,则required将仅对请求生效。属性不得同时标记为readOnlywriteOnlytrue。默认值为false
xml XML 对象 可以仅用于属性 schema。它对根 schema 没有影响。添加其他元数据以描述此属性的 XML 表示形式。
外部文档 外部文档对象 此 schema 的其他外部文档。
示例 任何 一个自由格式的属性,用于包含此 schema 的实例示例。为了表示无法在 JSON 或 YAML 中自然表示的示例,可以使用字符串值来包含示例,并在必要时进行转义。
已弃用 布尔值 指定 schema 已弃用,并且过渡到不再使用。默认值为false

此对象可以使用 规范扩展 进行扩展。

4.7.24.2.1 组合和继承(多态)

OpenAPI 规范允许使用 JSON Schema 的 allOf 属性组合和扩展模型定义,实际上提供了模型组合的功能。allOf 接收一个对象定义数组,这些定义会独立进行验证,但共同组成一个对象。

虽然组合提供了模型的可扩展性,但它并不意味着模型之间存在层次结构。为了支持多态性,OpenAPI 规范添加了 discriminator 字段。使用时,discriminator 将是决定哪个模式定义验证模型结构的属性的名称。因此,discriminator 字段必须是必填字段。有两种方法可以为继承实例定义鉴别器的值。

  • 使用模式名称。
  • 通过使用新值覆盖属性来覆盖模式名称。如果存在新值,则优先于模式名称。因此,没有给定 id 的内联模式定义不能用于多态性。
4.7.24.2.2 XML 建模

xml 属性允许在将 JSON 定义转换为 XML 时添加额外的定义。XML 对象包含有关可用选项的更多信息。

4.7.24.3 Schema 对象示例
4.7.24.3.1 原始示例
{
  "type": "string",
  "format": "email"
}
type: string
format: email
4.7.24.3.2 简单模型
{
  "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
4.7.24.3.3 具有 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'
4.7.24.3.4 具有示例的模型
{
  "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
4.7.24.3.5 具有组合的模型
{
  "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
4.7.24.3.6 具有多态支持的模型
{
  "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

4.7.25 Discriminator 对象

当请求体或响应有效负载可能是多种不同模式之一时,可以使用 discriminator 对象来帮助进行序列化、反序列化和验证。鉴别器是模式中的一个特定对象,用于根据与其关联的值向规范的使用者告知备用模式。

使用鉴别器时,将不考虑内联模式。

4.7.25.1 固定字段
字段名称 类型 描述
propertyName 字符串 必需。有效负载中包含鉴别器值的属性的名称。
mapping Map[string, string] 一个对象,用于保存有效负载值和模式名称或引用之间的映射。

仅当使用组合关键字 oneOfanyOfallOf 之一时,鉴别器属性才合法。

在 OAS 3.0 中,响应有效负载可以被描述为正好是任意数量的类型之一

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

这意味着有效负载必须通过验证与 CatDogLizard 描述的模式之一完全匹配。在这种情况下,鉴别器可以充当“提示”,以缩短验证和匹配模式的选择,这可能是代价高昂的操作,具体取决于模式的复杂性。然后,我们可以准确地描述哪个字段告诉我们使用哪个模式

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

现在的预期是,名为 pet_type 的属性必须存在于响应有效负载中,并且该值将对应于 OAS 文档中定义的模式的名称。因此,响应有效负载

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

将指示与该有效负载一起使用 Cat 模式。

在鉴别器字段的值与模式名称不匹配或隐式映射不可行的情况下,可以使用可选的 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: pet_type
    mapping:
      dog: '#/components/schemas/Dog'
      monster: 'https://gigantic-server.com/schemas/Monster/schema.json'

这里,鉴别器的 dog 将映射到模式 #/components/schemas/Dog,而不是 Dog 的默认(隐式)值。如果鉴别器的与隐式或显式映射不匹配,则无法确定任何模式,并且验证应该失败。映射键必须是字符串值,但工具可以将响应值转换为字符串以进行比较。

当与 anyOf 结构一起使用时,鉴别器的使用可以避免多个模式可能满足单个有效负载的情况下的歧义。

oneOfanyOf 的使用案例中,必须显式列出所有可能的模式。为了避免冗余,可以将鉴别器添加到父模式定义中,并且 allOf 结构中构成父模式的所有模式都可以用作备用模式。

例如

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

这样的有效负载

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

将指示使用 Cat 模式。同样,此模式

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

由于 mappings 元素中的定义,将映射到 Dog

4.7.26 XML 对象

一个元数据对象,允许更精细地定义 XML 模型。

使用数组时,不会推断 XML 元素名称(对于单数/复数形式),并且应该使用 name 属性添加该信息。请参阅示例以了解预期行为。

4.7.26.1 固定字段
字段名称 类型 描述
name 字符串 替换用于描述的模式属性的元素/属性的名称。在 items 中定义时,它将影响列表中各个 XML 元素的名称。当与 typearray 一起定义(在 items 之外)时,它将影响包装元素,并且仅当 wrappedtrue 时才会生效。如果 wrappedfalse,则将被忽略。
namespace 字符串 命名空间定义的 URI。值必须采用绝对 URI 的形式。
prefix 字符串 要用于name的前缀。
attribute 布尔值 声明属性定义是否转换为属性而不是元素。默认值为 false
wrapped 布尔值 可以仅用于数组定义。表示数组是包装的(例如,<books><book/><book/></books>)还是未包装的(<book/><book/>)。默认值为 false。仅当与 typearray 一起定义(在 items 之外)时,该定义才会生效。

此对象可以使用 规范扩展 进行扩展。

4.7.26.2 XML 对象示例

XML 对象定义的示例包含在模式对象的属性定义中,并附带其 XML 表示形式的示例。

4.7.26.2.1 无 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>
4.7.26.2.2 XML 名称替换
{
  "animals": {
    "type": "string",
    "xml": {
      "name": "animal"
    }
  }
}
animals:
  type: string
  xml:
    name: animal
<animal>...</animal>
4.7.26.2.3 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>
4.7.26.2.4 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>

4.7.27 Security Scheme 对象

定义可以在操作中使用的安全方案。支持的方案包括 HTTP 身份验证、API 密钥(作为标头或查询参数)、OAuth2 的常用流程(隐式、密码、应用程序和访问代码),如 [RFC6749] 中所定义,以及OpenID Connect Discovery

4.7.27.1 固定字段
字段名称 类型 应用于 描述
type 字符串 任何 必需。安全方案的类型。有效值为 "apiKey""http""oauth2""openIdConnect"
description 字符串 任何 安全方案的简短描述。[CommonMark] 语法可以用于富文本表示。
name 字符串 apiKey 必需。要使用的标头、查询或 Cookie 参数的名称。
in 字符串 apiKey 必需。API 密钥的位置。有效值为 "query""header""cookie"
scheme 字符串 http 必需。如 [RFC7235] 第 5.1 节 中所定义,要在 Authorization 标头中使用的 HTTP 授权方案的名称。
bearerFormat 字符串 http ("bearer") 提示客户端识别承载令牌的格式。承载令牌通常由授权服务器生成,因此此信息主要用于文档目的。
flows OAuth Flows 对象 oauth2 必需。一个包含流程类型支持配置信息的 对象。
openIdConnectUrl 字符串 openIdConnect 必需。用于发现 OAuth2 配置值的 OpenId Connect URL。此必须采用 URL 的形式。

此对象可以使用 规范扩展 进行扩展。

4.7.27.2 Security Scheme 对象示例
4.7.27.2.1 基本身份验证示例
{
  "type": "http",
  "scheme": "basic"
}
type: http
scheme: basic
4.7.27.2.2 API 密钥示例
{
  "type": "apiKey",
  "name": "api_key",
  "in": "header"
}
type: apiKey
name: api_key
in: header
4.7.27.2.3 JWT Bearer 示例
{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT",
}
type: http
scheme: bearer
bearerFormat: JWT
4.7.27.2.4 隐式 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

4.7.28 OAuth Flows 对象

允许配置支持的 OAuth 流程。

4.7.28.1 固定字段
字段名称 类型 描述
implicit OAuth Flow 对象 OAuth 隐式流程的配置
password OAuth Flow 对象 OAuth 资源所有者密码流程的配置
clientCredentials OAuth Flow 对象 OAuth 客户端凭据流程的配置。在 OpenAPI 2.0 中以前称为 application
authorizationCode OAuth Flow 对象 OAuth 授权码流程的配置。在 OpenAPI 2.0 中以前称为 accessCode

此对象可以使用 规范扩展 进行扩展。

4.7.29 OAuth Flow 对象

支持的 OAuth 流程的配置详细信息

4.7.29.1 固定字段
字段名称 类型 应用于 描述
authorizationUrl 字符串 oauth2 ("implicit", "authorizationCode") 必需。要用于此流程的授权 URL。此必须采用 URL 的形式。
tokenUrl 字符串 oauth2 ("password", "clientCredentials", "authorizationCode") 必需。要用于此流程的令牌 URL。此必须采用 URL 的形式。
refreshUrl 字符串 oauth2 用于获取刷新令牌的 URL。此必须采用 URL 的形式。
scopes Map[string, string] oauth2 必需。OAuth2 安全方案的可用范围。范围名称与其简短描述之间的映射。

此对象可以使用 规范扩展 进行扩展。

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

4.7.30 Security Requirement 对象

列出执行此操作所需的安全性方案。每个属性使用的名称必须对应于在安全方案组件对象中声明的安全方案。

包含多个方案的安全需求对象要求必须满足所有方案才能授权请求。这使得支持需要多个查询参数或 HTTP 标头来传递安全信息的情况成为可能。

当在OpenAPI 对象操作对象上定义安全需求对象的列表时,只需要满足列表中的安全需求对象之一即可授权请求。

4.7.30.1 模式化字段
字段模式 类型 描述
{name} [string] 每个名称必须对应于在安全方案组件对象中声明的安全方案。如果安全方案的类型为 "oauth2""openIdConnect",则该值为执行所需的一系列范围名称。对于其他安全方案类型,数组必须为空。
4.7.30.2 Security Requirement 对象示例
4.7.30.2.1 非 OAuth2 安全需求
{
  "api_key": []
}
api_key: []
4.7.30.2.2 OAuth2 安全需求
{
  "petstore_auth": [
    "write:pets",
    "read:pets"
  ]
}
petstore_auth:
- write:pets
- read:pets

4.8 规范扩展

虽然 OpenAPI 规范试图适应大多数用例,但可以在某些点添加其他数据以扩展规范。

扩展属性以模式化的字段实现,这些字段始终以"x-"作为前缀。

字段模式 类型 描述
^x- 任何 允许扩展 OpenAPI Schema。字段名称必须x-开头,例如x-internal-id。其值可以是null、基本类型、数组或对象。可以具有任何有效的 JSON 格式的值。

扩展可能被现有的工具支持,也可能不被支持,但这些工具也可以被扩展以添加请求的支持(如果工具是内部的或开源的)。

4.9 安全过滤

OpenAPI 规范中的一些对象可以被声明并保持为空,或者完全删除,即使它们本质上是 API 文档的核心。

这样做的原因是为了允许在文档上添加一层额外的访问控制。虽然本身不是规范的一部分,但某些库可以选择根据某种形式的身份验证/授权来允许访问文档的某些部分。

以下是两个示例

  1. 路径对象可以为空。这可能看起来违反直觉,但这可能告诉查看者他们来到了正确的位置,但无法访问任何文档。他们仍然可以访问信息对象,其中可能包含有关身份验证的更多信息。
  2. 路径项对象可以为空。在这种情况下,查看者将知道路径存在,但将无法查看其任何操作或参数。这与从路径对象中隐藏路径本身不同,因此用户将不知道它的存在。这允许文档提供者精细地控制查看者可以看到的内容。

A. 附录 A:修订历史

版本 日期 备注
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 Initiative
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 规范的第一个版本

B. 参考文献

B.1 规范性引用

[ABNF]
语法规范增强 BNF:ABNF。D. Crocker,编辑;P. Overell。IETF。2008 年 1 月。互联网标准。网址:https://www.rfc-editor.org/rfc/rfc5234
[CommonMark]
CommonMark 规范。网址:https://spec.commonmark.org/
[CommonMark-0.27]
CommonMark 规范,版本 0.27。John MacFarlane。2016 年 11 月 18 日。网址:https://spec.commonmark.org/0.27/
[IANA-HTTP-STATUS-CODES]
超文本传输协议 (HTTP) 状态代码注册表。IANA。网址:https://www.iana.org/assignments/http-status-codes/
[JSON-Reference]
JSON 引用。Paul Bryan;Kris Zyp。互联网工程任务组 (IETF)。2012 年 9 月 16 日。互联网草案。网址:https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03
[JSON-Schema-05]
JSON Schema:用于描述 JSON 文档的媒体类型。草案 5。Austin Wright。互联网工程任务组 (IETF)。2016 年 10 月 13 日。互联网草案。网址:https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00
[JSON-Schema-Validation-05]
JSON Schema 验证:用于 JSON 结构验证的词汇表。草案 5。Austin Wright;G. Luff。互联网工程任务组 (IETF)。2016 年 10 月 13 日。互联网草案。网址:https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
[RFC1866]
超文本标记语言 - 2.0。T. Berners-Lee;D. Connolly。IETF。1995 年 11 月。历史版本。网址:https://www.rfc-editor.org/rfc/rfc1866
[RFC2119]
RFC 中用于指示需求级别的关键词。S. Bradner。IETF。1997 年 3 月。最佳实践。网址:https://www.rfc-editor.org/rfc/rfc2119
[RFC3339]
互联网上的日期和时间:时间戳。G. Klyne;C. Newman。IETF。2002 年 7 月。建议标准。网址:https://www.rfc-editor.org/rfc/rfc3339
[RFC3986]
统一资源标识符 (URI):通用语法。T. Berners-Lee;R. Fielding;L. Masinter。IETF。2005 年 1 月。互联网标准。网址:https://www.rfc-editor.org/rfc/rfc3986
[RFC6570]
URI 模板。J. Gregorio;R. Fielding;M. Hadley;M. Nottingham;D. Orchard。IETF。2012 年 3 月。建议标准。网址:https://www.rfc-editor.org/rfc/rfc6570
[RFC6749]
OAuth 2.0 授权框架。D. Hardt,编辑。IETF。2012 年 10 月。建议标准。网址:https://www.rfc-editor.org/rfc/rfc6749
[RFC6838]
媒体类型规范和注册程序。N. Freed;J. Klensin;T. Hansen。IETF。2013 年 1 月。最佳实践。网址:https://www.rfc-editor.org/rfc/rfc6838
[RFC6901]
JavaScript 对象表示法 (JSON) 指针。P. Bryan,编辑;K. Zyp;M. Nottingham,编辑。IETF。2013 年 4 月。建议标准。网址:https://www.rfc-editor.org/rfc/rfc6901
[RFC7159]
JavaScript 对象表示法 (JSON) 数据交换格式。T. Bray,编辑。IETF。2014 年 3 月。建议标准。网址:https://www.rfc-editor.org/rfc/rfc7159
[RFC7230]
超文本传输协议 (HTTP/1.1):消息语法和路由。R. Fielding,编辑;J. Reschke,编辑。IETF。2014 年 6 月。建议标准。网址:https://httpwg.org/specs/rfc7230.html
[RFC7231]
超文本传输协议 (HTTP/1.1):语义和内容。R. Fielding,编辑;J. Reschke,编辑。IETF。2014 年 6 月。建议标准。网址:https://httpwg.org/specs/rfc7231.html
[RFC7235]
超文本传输协议 (HTTP/1.1):身份验证。R. Fielding,编辑;J. Reschke,编辑。IETF。2014 年 6 月。建议标准。网址:https://httpwg.org/specs/rfc7235.html
[RFC8174]
RFC 2119 关键词中大写和小写的不确定性。B. Leiba。IETF。2017 年 5 月。最佳实践。网址:https://www.rfc-editor.org/rfc/rfc8174
[YAML]
YAML Ain’t Markup Language (YAML™) 版本 1.2。Oren Ben-Kiki;Clark Evans;Ingy döt Net。2009 年 10 月 1 日。网址:http://yaml.org/spec/1.2/spec.html