OpenAPI 规范

(前身为 Swagger RESTful API 文档规范)

版本 2.0

本文档中的关键词“MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY”和“OPTIONAL”应按 RFC 2119 中所述进行解释。

Swagger 规范根据 Apache 许可证 2.0 版获得许可。

简介

Swagger™ 是一个用于描述和文档化 RESTful API 的项目。

Swagger 规范定义了一组描述此类 API 所需的文件。这些文件随后可由 Swagger-UI 项目用于显示 API，并由 Swagger-Codegen 用于生成各种语言的客户端。其他实用程序也可以利用生成的文件，例如测试工具。

修订历史

版本	日期	备注
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 规范的首次发布

定义

路径模板

路径模板是指使用花括号 ({}) 标记 URL 路径中的一部分，以便使用路径参数进行替换。

MIME 类型

MIME 类型定义分布在多个资源中。MIME 类型定义应符合 RFC 6838。

MIME 类型定义的一些可能示例

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

HTTP 状态码

HTTP 状态码用于指示执行操作的状态。可用状态码由 RFC 7231 和 IANA 状态码注册表描述。

规范

格式

描述符合 Swagger 规范的 RESTful API 的文件以 JSON 对象表示并符合 JSON 标准。YAML 作为 JSON 的超集，也可用于表示 Swagger 规范文件。

例如，如果某个字段被声明为具有数组值，则将使用 JSON 数组表示。

{
   "field" : [...]
}

尽管 API 使用 JSON 进行描述，但它并不对 API 本身强制要求 JSON 输入/输出。

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

模式公开了两种类型的字段：固定字段（具有声明的名称）和模式化字段（为字段名声明了正则表达式模式）。模式化字段可以多次出现，只要每个都具有唯一的名称。

文件结构

API 的 Swagger 表示由单个文件组成。然而，定义的某些部分可以根据用户的判断拆分为单独的文件。这适用于规范中的 $ref 字段，如 JSON Schema 定义所示。

按照惯例，Swagger 规范文件命名为 `swagger.json`。

数据类型

Swagger 规范中的原始数据类型基于 JSON-Schema 草案 4 支持的类型。模型使用 模式对象 描述，它是 JSON Schema 草案 4 的一个子集。

附加的原始数据类型 "file" 被 参数对象 和 响应对象 用于将参数类型或响应设置为文件。

原始类型具有一个可选的修饰符属性 format。Swagger 使用几种已知格式来更精细地定义所使用的数据类型。然而，format 属性是一个开放的 string 值属性，可以具有任何值以支持文档需求。诸如 "email"、"uuid" 等格式可以使用，即使它们未由本规范定义。不带 format 属性的类型遵循其在 JSON Schema 中的定义（file 类型除外，该类型已在上面定义）。Swagger 规范定义的格式有

常用名称	类型	格式	备注
integer	integer	int32	32 位有符号整数
long	integer	int64	64 位有符号整数
float	number	float
double	number	double
string	string
byte	string	byte	Base64 编码字符
binary	string	binary	任意八位字节序列
boolean	boolean
date	string	date	由 full-date 定义 - RFC3339
dateTime	string	date-time	由 date-time 定义 - RFC3339
password	string	password	用于提示 UI 需要对输入进行遮掩。

模式

Swagger 对象

这是 API 规范的根文档对象。它将以前的资源列表和 API 声明（1.2 版及更早版本）合并到一个文档中。

固定字段

字段名称	类型	描述
swagger	string	必需。指定正在使用的 Swagger 规范版本。Swagger UI 和其他客户端可以使用它来解释 API 列表。该值**必须**是 "2.0"。
info	信息对象	必需。提供关于 API 的元数据。如果需要，客户端可以使用该元数据。
host	string	提供 API 的主机（名称或 IP）。这**必须**仅是主机，不包括方案和子路径。它**可以**包含端口。如果未包含 host，则使用提供文档的主机（包括端口）。host 不支持 路径模板。
basePath	string	API 服务的基础路径，相对于 host。如果未包含，API 将直接在 host 下提供。该值**必须**以斜杠 (/) 开头。basePath 不支持 路径模板。
schemes	[string]	API 的传输协议。值**必须**来自以下列表："http"、"https"、"ws"、"wss"。如果未包含 schemes，则默认使用的方案是用于访问 Swagger 定义本身的方案。
consumes	[string]	API 可以消费的 MIME 类型列表。这对于所有 API 都是全局的，但可以在特定的 API 调用中被覆盖。值**必须**符合 MIME 类型 中所述。
produces	[string]	API 可以生产的 MIME 类型列表。这对于所有 API 都是全局的，但可以在特定的 API 调用中被覆盖。值**必须**符合 MIME 类型 中所述。
paths	路径对象	必需。API 可用的路径和操作。
definitions	定义对象	一个用于保存操作产生和消费的数据类型的对象。
parameters	参数定义对象	一个用于保存可在操作中重用的参数的对象。此属性*不*定义所有操作的全局参数。
responses	响应定义对象	一个用于保存可在操作中重用的响应的对象。此属性*不*定义所有操作的全局响应。
securityDefinitions	安全定义对象	可在整个规范中使用的安全方案定义。
security	[安全要求对象]	声明应用于整个 API 的安全方案。值列表描述了可以使用的替代安全方案（即，安全要求之间存在逻辑或关系）。单个操作可以覆盖此定义。
tags	[标签对象]	规范使用的标签列表，附带额外的元数据。标签的顺序可用于反映解析工具的顺序。并非 操作对象 使用的所有标签都必须声明。未声明的标签可以随机组织或根据工具的逻辑组织。列表中的每个标签名称**必须**是唯一的。
externalDocs	外部文档对象	附加外部文档。

模式化对象

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

信息对象

该对象提供关于 API 的元数据。如果需要，客户端可以使用该元数据，并且可以方便地在 Swagger-UI 中显示。

固定字段

字段名称	类型	描述
title	string	必需。应用程序的标题。
description	string	应用程序的简短描述。GFM 语法 可用于富文本表示。
termsOfService	string	API 的服务条款。
contact	联系人对象	公开 API 的联系信息。
license	许可证对象	公开 API 的许可证信息。
version	string	必需。提供应用程序 API 的版本（不要与规范版本混淆）。

模式化对象

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

信息对象示例

{
  "title": "Swagger Sample App",
  "description": "This is a sample server Petstore server.",
  "termsOfService": "https://swagger.org.cn/terms/",
  "contact": {
    "name": "API Support",
    "url": "http://www.swagger.io/support",
    "email": "[email protected]"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://apache.ac.cn/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

title: Swagger Sample App
description: This is a sample server Petstore server.
termsOfService: https://swagger.org.cn/terms/
contact:
  name: API Support
  url: http://www.swagger.io/support
  email: [email protected]
license:
  name: Apache 2.0
  url: https://apache.ac.cn/licenses/LICENSE-2.0.html
version: 1.0.1

联系人对象

公开 API 的联系信息。

固定字段

字段名称	类型	描述
name	string	联系人/组织的标识名称。
url	string	指向联系信息的 URL。**必须**是 URL 格式。
email	string	联系人/组织的电子邮件地址。**必须**是电子邮件地址格式。

模式化对象

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

联系人对象示例

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

name: API Support
url: http://www.swagger.io/support
email: [email protected]

许可证对象

公开 API 的许可证信息。

固定字段

字段名称	类型	描述
name	string	必需。API 使用的许可证名称。
url	string	API 使用的许可证的 URL。**必须**是 URL 格式。

模式化对象

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

许可证对象示例

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

name: Apache 2.0
url: https://apache.ac.cn/licenses/LICENSE-2.0.html

路径对象

包含各个端点的相对路径。路径会附加到 basePath 以构建完整的 URL。由于 ACL 限制，路径可能为空。

模式化字段

字段模式	类型	描述
/{path}	路径项对象	到单个端点的相对路径。字段名称**必须**以斜杠开头。路径会附加到 basePath 以构建完整的 URL。路径模板 是允许的。
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

路径对象示例

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

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

路径项对象

描述单个路径上可用的操作。由于 ACL 限制，路径项可能为空。路径本身仍暴露给文档查看器，但他们将不知道哪些操作和参数可用。

固定字段

字段名称	类型	描述
$ref	string	允许外部定义此路径项。引用的结构**必须**是 路径项对象 的格式。如果引用定义与此路径项的定义之间存在冲突，则行为是未定义的。
get	操作对象	此路径上 GET 操作的定义。
put	操作对象	此路径上 PUT 操作的定义。
post	操作对象	此路径上 POST 操作的定义。
delete	操作对象	此路径上 DELETE 操作的定义。
options	操作对象	此路径上 OPTIONS 操作的定义。
head	操作对象	此路径上 HEAD 操作的定义。
patch	操作对象	此路径上 PATCH 操作的定义。
parameters	[参数对象 | 引用对象]	适用于此路径下描述的所有操作的参数列表。这些参数可以在操作级别被覆盖，但不能在那里被删除。列表**不得**包含重复的参数。唯一参数由 名称 和 位置 的组合定义。列表可以使用 引用对象 链接到 Swagger 对象的参数 中定义的参数。最多只能有一个“body”参数。

模式化字段

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

路径项对象示例

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

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  produces:
  - application/json
  - text/html
  responses:
    '200':
      description: pet response
      schema:
        type: array
        items:
          $ref: '#/definitions/Pet'
    default:
      description: error payload
      schema:
        $ref: '#/definitions/ErrorModel'
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  type: array
  items:
    type: string
  collectionFormat: csv

操作对象

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

固定字段

字段名称	类型	描述
tags	[string]	用于 API 文档控制的标签列表。标签可用于按资源或任何其他限定符对操作进行逻辑分组。
summary	string	操作功能的简短摘要。为了在 swagger-ui 中获得最大可读性，此字段**应**少于 120 个字符。
description	string	操作行为的详细解释。GFM 语法 可用于富文本表示。
externalDocs	外部文档对象	此操作的附加外部文档。
operationId	string	用于标识操作的唯一字符串。该 ID **必须**在 API 中描述的所有操作中是唯一的。工具和库**可以**使用 operationId 来唯一标识一个操作，因此，建议遵循常见的编程命名约定。
consumes	[string]	操作可以消费的 MIME 类型列表。这会覆盖 Swagger 对象中的 consumes 定义。可以使用空值清除全局定义。值**必须**符合 MIME 类型 中所述。
produces	[string]	操作可以生产的 MIME 类型列表。这会覆盖 Swagger 对象中的 produces 定义。可以使用空值清除全局定义。值**必须**符合 MIME 类型 中所述。
parameters	[参数对象 | 引用对象]	适用于此操作的参数列表。如果参数已在 路径项 中定义，则新定义将覆盖它，但不能将其删除。列表**不得**包含重复的参数。唯一参数由 名称 和 位置 的组合定义。列表可以使用 引用对象 链接到 Swagger 对象的参数 中定义的参数。最多只能有一个“body”参数。
responses	响应对象	必需。执行此操作后返回的可能响应列表。
schemes	[string]	操作的传输协议。值**必须**来自以下列表："http"、"https"、"ws"、"wss"。该值会覆盖 Swagger 对象 schemes 定义。
deprecated	boolean	声明此操作已弃用。应避免使用已声明的操作。默认值为 false。
security	[安全要求对象]	声明应用于此操作的安全方案。值列表描述了可以使用的替代安全方案（即，安全要求之间存在逻辑或关系）。此定义会覆盖任何已声明的顶级 security。要删除顶级安全声明，可以使用空数组。

模式化对象

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

操作对象示例

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

tags:
- pet
summary: Updates a pet in the store with form data
description: ""
operationId: updatePetWithForm
consumes:
- application/x-www-form-urlencoded
produces:
- application/json
- application/xml
parameters:
- name: petId
  in: path
  description: ID of pet that needs to be updated
  required: true
  type: string
- name: name
  in: formData
  description: Updated name of the pet
  required: false
  type: string
- name: status
  in: formData
  description: Updated status of the pet
  required: false
  type: string
responses:
  '200':
    description: Pet updated.
  '405':
    description: Invalid input
security:
- petstore_auth:
  - write:pets
  - read:pets

外部文档对象

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

固定字段

字段名称	类型	描述
description	string	目标文档的简短描述。GFM 语法 可用于富文本表示。
url	string	必需。目标文档的 URL。值**必须**是 URL 格式。

模式化对象

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

外部文档对象示例

{
  "description": "Find more info here",
  "url": "https://swagger.org.cn"
}

description: Find more info here
url: https://swagger.org.cn

参数对象

描述单个操作参数。

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

有五种可能的参数类型。

• Path - 与 路径模板 一起使用，其中参数值实际上是操作 URL 的一部分。这不包括 API 的主机或基础路径。例如，在 /items/{itemId} 中，路径参数是 itemId。
• Query - 附加到 URL 的参数。例如，在 /items?id=### 中，查询参数是 id。
• Header - 作为请求一部分的预期自定义头。
• Body - 附加到 HTTP 请求的有效载荷。由于只能有一个有效载荷，因此只能有一个主体参数。主体参数的名称对参数本身没有影响，仅用于文档目的。由于表单参数也包含在有效载荷中，因此主体和表单参数不能在同一操作中同时存在。
• Form - 用于描述 HTTP 请求的有效载荷，当 application/x-www-form-urlencoded、multipart/form-data 或两者都被用作请求的内容类型时（在 Swagger 的定义中，是操作的 consumes 属性）。这是唯一可以用于发送文件的参数类型，因此支持 file 类型。由于表单参数在有效载荷中发送，因此它们不能与同一操作的主体参数一起声明。表单参数的格式根据使用的内容类型而不同（有关更多详细信息，请查阅 http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4）
  • application/x-www-form-urlencoded - 类似于查询参数的格式，但作为有效载荷。例如，foo=1&bar=swagger - foo 和 bar 都是表单参数。这通常用于传输简单参数。
  • multipart/form-data - 每个参数在有效载荷中占用一个部分，并带有内部头。例如，对于头 Content-Disposition: form-data; name="submit-name"，参数的名称是 submit-name。这种类型的表单参数更常用于文件传输。

固定字段

字段名称	类型	描述
name	string	必需。参数的名称。参数名称区分大小写。 如果 in 是 "path"，则 name 字段**必须**与 路径对象 中 path 字段的关联路径段相对应。有关更多信息，请参阅 路径模板。 对于所有其他情况，name 与根据 in 属性使用的参数名称相对应。
in	string	必需。参数的位置。可能的值为 "query", "header", "path", "formData" 或 "body"。
description	string	参数的简要描述。这可以包含使用示例。GFM 语法 可用于富文本表示。
required	boolean	确定此参数是否强制。如果参数 in 是 "path"，则此属性是必需的，其值**必须**为 true。否则，可以包含此属性，其默认值为 false。

如果 in 是 "body"

字段名称	类型	描述
schema	模式对象	必需。定义主体参数所用类型的模式。

如果 in 是除 "body" 以外的任何值

字段名称	类型	描述
type	string	必需。参数的类型。由于参数不位于请求主体中，因此它仅限于简单类型（即非对象）。值**必须**是 "string"、"number"、"integer"、"boolean"、"array" 或 "file" 之一。如果 type 是 "file"，则 consumes **必须**是 "multipart/form-data"、" application/x-www-form-urlencoded" 或两者，并且参数**必须** in "formData"。
format	string	前面提到的 type 的扩展格式。有关更多详细信息，请参阅 数据类型格式。
allowEmptyValue	boolean	设置传递空值参数的能力。这仅适用于 query 或 formData 参数，并允许您只发送带有名称的参数或空值。默认值为 false。
items	项对象	如果 type 是 "array" 则必需。描述数组中项的类型。
collectionFormat	string	如果使用数组类型，则确定数组的格式。可能的值为 csv - 逗号分隔值 foo,bar。 ssv - 空格分隔值 foo bar。 tsv - 制表符分隔值 foo\tbar。 pipes - 管道分隔值 foo|bar。 multi - 对应于多个参数实例，而不是单个实例的多个值 foo=bar&foo=baz。这仅对 in "query" 或 "formData" 的参数有效。 默认值为 csv。
default	*	声明服务器在未提供参数时将使用的参数值，例如，如果客户端请求中未提供“count”来控制每页结果的数量，则可能默认为 100。（注意：“default”对于必需参数没有意义。）请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2。与 JSON Schema 不同，此值**必须**符合为此参数定义的 type。
maximum	number	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2。
exclusiveMaximum	boolean	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2。
minimum	number	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3。
exclusiveMinimum	boolean	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3。
maxLength	integer	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1。
minLength	integer	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2。
pattern	string	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3。
maxItems	integer	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2。
minItems	integer	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3。
uniqueItems	boolean	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4。
enum	[*]	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1。
multipleOf	number	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1。

模式化字段

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

参数对象示例

主体参数

具有引用模式定义的主体参数（通常用于模型定义）

{
  "name": "user",
  "in": "body",
  "description": "user to add to the system",
  "required": true,
  "schema": {
    "$ref": "#/definitions/User"
  }
}

name: user
in: body
description: user to add to the system
required: true
schema:
  $ref: '#/definitions/User'

一个字符串值数组的主体参数

{
  "name": "user",
  "in": "body",
  "description": "user to add to the system",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}

name: user
in: body
description: user to add to the system
required: true
schema:
  type: array
  items:
    type: string

其他参数

带有 64 位整数数组的头参数

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

name: token
in: header
description: token to be passed as a header
required: true
type: array
items:
  type: integer
  format: int64
collectionFormat: csv

一个字符串值的路径参数

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

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

一个可选的字符串值查询参数，通过重复查询参数允许多个值

{
  "name": "id",
  "in": "query",
  "description": "ID of the object to fetch",
  "required": false,
  "type": "array",
  "items": {
    "type": "string"
  },
  "collectionFormat": "multi"
}

name: id
in: query
description: ID of the object to fetch
required: false
type: array
items:
  type: string
collectionFormat: multi

带有文件类型用于文件上传的表单数据

{
  "name": "avatar",
  "in": "formData",
  "description": "The avatar of the user",
  "required": true,
  "type": "file"
}

name: avatar
in: formData
description: The avatar of the user
required: true
type: file

项对象

JSON-Schema 的 items 对象的一个受限子集。它用于不位于 in "body" 的参数定义。

固定字段

字段名称	类型	描述
type	string	必需。数组的内部类型。值**必须**是 "string"、"number"、"integer"、"boolean" 或 "array" 之一。不允许使用文件和模型。
format	string	前面提到的 type 的扩展格式。有关更多详细信息，请参阅 数据类型格式。
items	项对象	如果 type 是 "array" 则必需。描述数组中项的类型。
collectionFormat	string	如果使用数组类型，则确定数组的格式。可能的值为 csv - 逗号分隔值 foo,bar。 ssv - 空格分隔值 foo bar。 tsv - 制表符分隔值 foo\tbar。 pipes - 管道分隔值 foo|bar。 默认值为 csv。
default	*	声明服务器在未提供项时将使用的项值。（注意：“default”对于必需项没有意义。）请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2。与 JSON Schema 不同，此值**必须**符合为此数据类型定义的 type。
maximum	number	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2。
exclusiveMaximum	boolean	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2。
minimum	number	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3。
exclusiveMinimum	boolean	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3。
maxLength	integer	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1。
minLength	integer	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2。
pattern	string	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3。
maxItems	integer	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2。
minItems	integer	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3。
uniqueItems	boolean	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4。
enum	[*]	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1。
multipleOf	number	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1。

模式化对象

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

项对象示例

项必须是字符串类型，且最小长度为 2 个字符

{
    "type": "string",
    "minLength": 2
}

type: string
minLength: 2

数组的数组，内部数组为整数类型，数字必须在 0 到 63（含）之间

{
    "type": "array",
    "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 63
    }
}

type: array
items:
  type: integer
  minimum: 0
  maximum: 63

响应对象

操作预期响应的容器。该容器将 HTTP 响应代码映射到预期响应。文档不一定需要涵盖所有可能的 HTTP 响应代码，因为它们可能无法提前得知。然而，文档应涵盖成功的操作响应和任何已知错误。

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

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

固定字段

字段名称	类型	描述
default	响应对象 | 引用对象	除了为特定 HTTP 响应代码声明的响应之外的响应文档。它可用于涵盖未声明的响应。引用对象 可用于链接到在 Swagger 对象的响应 部分中定义的响应。

模式化字段

字段模式	类型	描述
{HTTP 状态码}	响应对象 | 引用对象	任何 HTTP 状态码 都可以用作属性名称（每个 HTTP 状态码一个属性）。描述该 HTTP 状态码的预期响应。引用对象 可用于链接到在 Swagger 对象的响应 部分中定义的响应。
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

响应对象示例

200 响应表示操作成功，其他情况的默认响应（暗示错误）

{
  "200": {
    "description": "a pet to be returned",
    "schema": {
      "$ref": "#/definitions/Pet"
    }
  },
  "default": {
    "description": "Unexpected error",
    "schema": {
      "$ref": "#/definitions/ErrorModel"
    }
  }
}

'200':
  description: a pet to be returned
  schema:
    $ref: '#/definitions/Pet'
default:
  description: Unexpected error
  schema:
    $ref: '#/definitions/ErrorModel'

响应对象

描述 API 操作的单个响应。

固定字段

字段名称	类型	描述
description	string	必需。响应的简短描述。GFM 语法 可用于富文本表示。
schema	模式对象	响应结构的定义。它可以是原始类型、数组或对象。如果此字段不存在，则表示响应中不返回任何内容。作为 模式对象 的扩展，其根 type 值也可以是 "file"。这**应**伴随相关的 produces MIME 类型。
headers	头对象	随响应发送的头列表。
examples	示例对象	响应消息的示例。

模式化对象

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

响应对象示例

复杂类型数组的响应

{
  "description": "A complex object array response",
  "schema": {
    "type": "array",
    "items": {
      "$ref": "#/definitions/VeryComplexType"
    }
  }
}

description: A complex object array response
schema:
  type: array
  items:
    $ref: '#/definitions/VeryComplexType'

字符串类型的响应

{
  "description": "A simple string response",
  "schema": {
    "type": "string"
  }
}

description: A simple string response
schema:
  type: string

带有头的响应

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

description: A simple string response
schema:
  type: string
headers:
  X-Rate-Limit-Limit:
    description: The number of allowed requests in the current period
    type: integer
  X-Rate-Limit-Remaining:
    description: The number of remaining requests in the current period
    type: integer
  X-Rate-Limit-Reset:
    description: The number of seconds left in the current period
    type: integer

无返回值的响应

{
  "description": "object created"
}

description: object created

头对象

列出可作为响应一部分发送的头。

模式化字段

字段模式	类型	描述
{name}	头对象	属性的名称对应于头的名称。值描述了头的类型。

头对象示例

限速头

{
    "X-Rate-Limit-Limit": {
        "description": "The number of allowed requests in the current period",
        "type": "integer"
    },
    "X-Rate-Limit-Remaining": {
        "description": "The number of remaining requests in the current period",
        "type": "integer"
    },
    "X-Rate-Limit-Reset": {
        "description": "The number of seconds left in the current period",
        "type": "integer"
    }
}

X-Rate-Limit-Limit:
  description: The number of allowed requests in the current period
  type: integer
X-Rate-Limit-Remaining:
  description: The number of remaining requests in the current period
  type: integer
X-Rate-Limit-Reset:
  description: The number of seconds left in the current period
  type: integer

示例对象

允许共享操作响应的示例。

模式化字段

字段模式	类型	描述
{MIME 类型}	任意	属性的名称**必须**是操作 produces 值之一（隐式或继承）。该值**应**是此类响应的示例。

示例对象示例

Pet 数据类型的 application/json MIME 类型示例响应

{
  "application/json": {
    "name": "Puma",
    "type": "Dog",
    "color": "Black",
    "gender": "Female",
    "breed": "Mixed"
  }
}

application/json:
  name: Puma
  type: Dog
  color: Black
  gender: Female
  breed: Mixed

头对象

字段名称	类型	描述
description	string	头的简短描述。
type	string	必需。对象的类型。值**必须**是 "string"、"number"、"integer"、"boolean" 或 "array" 之一。
format	string	前面提到的 type 的扩展格式。有关更多详细信息，请参阅 数据类型格式。
items	项对象	如果 type 是 "array" 则必需。描述数组中项的类型。
collectionFormat	string	如果使用数组类型，则确定数组的格式。可能的值为 csv - 逗号分隔值 foo,bar。 ssv - 空格分隔值 foo bar。 tsv - 制表符分隔值 foo\tbar。 pipes - 管道分隔值 foo|bar。 默认值为 csv。
default	*	声明服务器在未提供头时将使用的头值。（注意：“default”对于必需头没有意义。）请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2。与 JSON Schema 不同，此值**必须**符合为此头定义的 type。
maximum	number	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2。
exclusiveMaximum	boolean	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2。
minimum	number	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3。
exclusiveMinimum	boolean	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3。
maxLength	integer	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1。
minLength	integer	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2。
pattern	string	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3。
maxItems	integer	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2。
minItems	integer	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3。
uniqueItems	boolean	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4.
enum	[*]	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1。
multipleOf	number	参见 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1。

模式化对象

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

头对象示例

一个简单的整数类型头

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

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

标签对象

允许向 操作对象 使用的单个标签添加元数据。并非每个使用的标签都必须有一个标签对象。

固定字段

字段名称	类型	描述
name	string	必需。标签的名称。
description	string	标签的简短描述。GFM 语法 可用于富文本表示。
externalDocs	外部文档对象	此标签的附加外部文档。

模式化字段

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

标签对象示例

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

name: pet
description: Pets operations

引用对象

一个简单的对象，允许引用规范中的其他定义。它可用于引用在顶层定义的参数和响应以进行重用。

引用对象是一个 JSON 引用，它使用 JSON 指针 作为其值。对于本规范，仅支持 规范解引用。

固定字段

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

引用对象示例

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

$ref: '#/definitions/Pet'

相对模式文件示例

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

$ref: 'Pet.yaml'

带有嵌入式模式的相对文件示例

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

$ref: 'definitions.yaml#/Pet'

模式对象

模式对象允许定义输入和输出数据类型。这些类型可以是对象，也可以是原始类型和数组。此对象基于 JSON Schema 规范草案 4，并使用其预定义子集。在此子集之上，本规范提供了扩展，以允许更完整的文档。

有关这些属性的更多信息可在 JSON Schema 核心 和 JSON Schema 验证 中找到。除非另有说明，属性定义遵循此处引用的 JSON Schema 规范。

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

• $ref - 作为 JSON 引用
• format（有关更多详细信息，请参阅 数据类型格式）
• title
• description（GFM 语法 可用于富文本表示）
• default（与 JSON Schema 不同，该值**必须**符合模式对象定义的类型）
• multipleOf
• maximum
• exclusiveMaximum
• minimum
• exclusiveMinimum
• maxLength
• minLength
• pattern
• maxItems
• minItems
• uniqueItems
• maxProperties
• minProperties
• required
• enum
• 类型

以下属性取自 JSON Schema 定义，但其定义已根据 Swagger 规范进行了调整。它们的定义与 JSON Schema 中的定义相同，只是在原始定义引用 JSON Schema 定义的地方，改用 模式对象 定义。

• items
• allOf
• properties
• additionalProperties

除了 JSON Schema 子集字段外，以下字段可用于进一步的模式文档。

固定字段

字段名称	类型	描述
discriminator	string	增加对多态性的支持。discriminator 是用于区分继承此模式的其他模式的模式属性名称。使用的属性名称**必须**在此模式中定义，并且**必须**在 required 属性列表中。使用时，该值**必须**是此模式或任何继承此模式的模式的名称。
readOnly	boolean	仅与模式 "properties" 定义相关。声明此属性为“只读”。这意味着它**可以**作为响应的一部分发送，但**不得**作为请求的一部分发送。被标记为 readOnly 为 true 的属性**不应**出现在定义模式的 required 列表中。默认值为 false。
xml	XML 对象	这**可以**仅用于属性模式。它对根模式没有影响。添加附加元数据以描述此属性的 XML 表示格式。
externalDocs	外部文档对象	此模式的附加外部文档。
example	任意	一个自由格式的属性，用于包含此模式实例的示例。

模式化对象

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

组合与继承（多态性）

Swagger 允许使用 JSON Schema 的 allOf 属性组合和扩展模型定义，从而实现模型组合。allOf 接收一个对象定义数组，这些定义经过独立验证，但共同组成一个单一对象。

尽管组合提供了模型可扩展性，但它不意味着模型之间存在层次结构。为了支持多态性，Swagger 增加了对 discriminator 字段的支持。使用时，discriminator 将是用于决定使用哪个模式定义来验证模型结构的属性名称。因此，discriminator 字段**必须**是必填字段。所选属性的值必须是 definitions 属性下赋予模型的友好名称。因此，没有给定 ID 的内联模式定义不能用于多态性。

XML 建模

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

模式对象示例

原始类型示例

与早期版本的 Swagger 不同，模式定义也可以用于描述原始类型和数组。

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

type: string
format: email

简单模型

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

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

带有映射/字典属性的模型

对于简单的字符串到字符串映射

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

type: object
additionalProperties:
  type: string

对于字符串到模型的映射

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

type: object
additionalProperties:
  $ref: '#/definitions/ComplexModel'

带有示例的模型

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

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

带有组合的模型

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

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

带有多态性支持的模型

{
  "definitions": {
    "Pet": {
      "type": "object",
      "discriminator": "petType",
      "properties": {
        "name": {
          "type": "string"
        },
        "petType": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "petType"
      ]
    },
    "Cat": {
      "description": "A representation of a cat",
      "allOf": [
        {
          "$ref": "#/definitions/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",
      "allOf": [
        {
          "$ref": "#/definitions/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"
          ]
        }
      ]
    }
  }
}

definitions:
  Pet:
    type: object
    discriminator: petType
    properties:
      name:
        type: string
      petType:
        type: string
    required:
    - name
    - petType
  Cat:
    description: A representation of a cat
    allOf:
    - $ref: '#/definitions/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
    allOf:
    - $ref: '#/definitions/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

XML 对象

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

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

固定字段

字段名称	类型	描述
name	string	替换用于描述模式属性的元素/属性名称。当在项对象 (items) 中定义时，它将影响列表中各个 XML 元素的名称。当与 type 为 array (在 items 之外) 一起定义时，它将影响包装元素，并且仅当 wrapped 为 true 时。如果 wrapped 为 false，则将被忽略。
namespace	string	命名空间定义的 URL。值**应**是 URL 格式。
prefix	string	用于 名称 的前缀。
attribute	boolean	声明属性定义是转换为属性而不是元素。默认值为 false。
wrapped	boolean	**可以**仅用于数组定义。表示数组是包装的（例如，<books><book/><book/></books>）还是非包装的（<book/><book/>）。默认值为 false。该定义仅当与 type 为 array（在 items 之外）一起定义时生效。

模式化对象

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

XML 对象示例

XML 对象定义的示例包含在 模式对象 的属性定义中，并附带其 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": "https://swagger.org.cn/schema/sample",
          "prefix": "sample"
        }
      }
    }
  }
}

Person:
  type: object
  properties:
    id:
      type: integer
      format: int32
      xml:
        attribute: true
    name:
      type: string
      xml:
        namespace: https://swagger.org.cn/schema/sample
        prefix: sample

<Person id="123">
    <sample:name xmlns:sample="https://swagger.org.cn/schema/sample">example</sample:name>
</Person>

XML 数组

更改元素名称

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

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

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

外部 `name` 属性对 XML 没有影响

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

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

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

即使数组被包装，如果没有明确定义名称，内部和外部都将使用相同的名称

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

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

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

为克服上述示例，可以使用以下定义

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

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

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

同时影响内部和外部名称

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

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

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

如果我们更改外部元素而不更改内部元素

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

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

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

定义对象

一个用于保存操作可以消费和生产的数据类型的对象。这些数据类型可以是原始类型、数组或模型。

模式化字段

字段模式	类型	描述
{name}	模式对象	单个定义，将“名称”映射到其定义的模式。

定义对象示例

{
  "Category": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int64"
      },
      "name": {
        "type": "string"
      }
    }
  },
  "Tag": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int64"
      },
      "name": {
        "type": "string"
      }
    }
  }
}

Category:
  type: object
  properties:
    id:
      type: integer
      format: int64
    name:
      type: string
Tag:
  type: object
  properties:
    id:
      type: integer
      format: int64
    name:
      type: string

参数定义对象

一个用于保存可在操作中重用的参数的对象。参数定义可以引用此处定义的参数。

这*不*定义全局操作参数。

模式化字段

字段模式	类型	描述
{name}	参数对象	单个参数定义，将“名称”映射到其定义的参数。

参数定义对象示例

{
  "skipParam": {
    "name": "skip",
    "in": "query",
    "description": "number of items to skip",
    "required": true,
    "type": "integer",
    "format": "int32"
  },
  "limitParam": {
    "name": "limit",
    "in": "query",
    "description": "max records to return",
    "required": true,
    "type": "integer",
    "format": "int32"
  }
}

skipParam:
  name: skip
  in: query
  description: number of items to skip
  required: true
  type: integer
  format: int32
limitParam:
  name: limit
  in: query
  description: max records to return
  required: true
  type: integer
  format: int32

响应定义对象

一个用于保存可在操作中重用的响应的对象。响应定义可以引用此处定义的响应。

这*不*定义全局操作响应。

模式化字段

字段模式	类型	描述
{name}	响应对象	单个响应定义，将“名称”映射到其定义的响应。

响应定义对象示例

{
  "NotFound": {
    "description": "Entity not found."
  },
  "IllegalInput": {
  	"description": "Illegal input for operation."
  },
  "GeneralError": {
  	"description": "General Error",
  	"schema": {
  		"$ref": "#/definitions/GeneralError"
  	}
  }
}

NotFound:
  description: Entity not found.
IllegalInput:
  description: Illegal input for operation.
GeneralError:
  description: General Error
  schema:
    $ref: '#/definitions/GeneralError'

安全定义对象

规范中可用的安全方案声明。这不会对操作强制执行安全方案，仅用于提供每个方案的相关详细信息。

模式化字段

字段模式	类型	描述
{name}	安全方案对象	单个安全方案定义，将“名称”映射到其定义的方案。

安全定义对象示例

{
  "api_key": {
    "type": "apiKey",
    "name": "api_key",
    "in": "header"
  },
  "petstore_auth": {
    "type": "oauth2",
    "authorizationUrl": "https://swagger.org.cn/api/oauth/dialog",
    "flow": "implicit",
    "scopes": {
      "write:pets": "modify pets in your account",
      "read:pets": "read your pets"
    }
  }
}

api_key:
  type: apiKey
  name: api_key
  in: header
petstore_auth:
  type: oauth2
  authorizationUrl: https://swagger.org.cn/api/oauth/dialog
  flow: implicit
  scopes:
    write:pets: modify pets in your account
    read:pets: read your pets

安全方案对象

允许定义操作可以使用的安全方案。支持的方案有基本认证、API 密钥（作为头或查询参数）和 OAuth2 的常见流程（隐式、密码、应用程序和访问代码）。

固定字段

字段名称	类型	有效性	描述
type	string	任意	必需。安全方案的类型。有效值为 "basic"、"apiKey" 或 "oauth2"。
description	string	任意	安全方案的简短描述。
name	string	apiKey	必需。要使用的头或查询参数的名称。
in	string	apiKey	必需。API 密钥的位置。有效值为 "query" 或 "header"。
flow	string	oauth2	必需。OAuth2 安全方案使用的流程。有效值为 "implicit"、"password"、"application" 或 "accessCode"。
authorizationUrl	string	oauth2 ("implicit", "accessCode")	必需。此流程要使用的授权 URL。这**应**是 URL 格式。
tokenUrl	string	oauth2 ("password", "application", "accessCode")	必需。此流程要使用的令牌 URL。这**应**是 URL 格式。
scopes	作用域对象	oauth2	必需。OAuth2 安全方案的可用作用域。

模式化字段

字段名称	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

安全方案对象示例

基本认证示例

{
  "type": "basic"
}

type: basic

API 密钥示例

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

type: apiKey
name: api_key
in: header

隐式 OAuth2 示例

{
  "type": "oauth2",
  "authorizationUrl": "https://swagger.org.cn/api/oauth/dialog",
  "flow": "implicit",
  "scopes": {
    "write:pets": "modify pets in your account",
    "read:pets": "read your pets"
  }
}

type: oauth2
authorizationUrl: https://swagger.org.cn/api/oauth/dialog
flow: implicit
scopes:
  write:pets: modify pets in your account
  read:pets: read your pets

作用域对象

列出 OAuth2 安全方案的可用作用域。

模式化字段

字段模式	类型	描述
{名称}	string	将作用域名称映射到其简短描述（作为属性的值）。

模式化对象

字段模式	类型	描述
^x-	任意	允许对 Swagger 模式进行扩展。字段名称**必须**以 x- 开头，例如 x-internal-id。值可以是 null、原始类型、数组或对象。有关更多详细信息，请参阅 供应商扩展。

作用域对象示例

{
  "write:pets": "modify pets in your account",
  "read:pets": "read your pets"
}

write:pets: modify pets in your account
read:pets: read your pets

安全要求对象

列出执行此操作所需的安全方案。该对象可以声明多个安全方案，这些方案都是必需的（即，方案之间存在逻辑“与”关系）。

每个属性使用的名称必须对应于在安全定义中声明的安全方案。

模式化字段

字段模式	类型	描述
{名称}	[string]	每个名称必须对应于在安全定义中声明的安全方案。如果安全方案的类型为"oauth2"，则值是执行所需的作用域名称列表。对于其他安全方案类型，该数组必须为空。

安全要求对象示例

非 OAuth2 安全要求

{
  "api_key": []
}

api_key: []

OAuth2 安全要求

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

petstore_auth:
- write:pets
- read:pets

规范扩展

虽然 Swagger 规范力求满足大多数用例，但可以在某些点添加额外数据以扩展规范。

扩展属性总是以"x-"为前缀，并且可以拥有任何有效的 JSON 格式值。

可用工具可能支持也可能不支持这些扩展，但也可以扩展这些工具以添加所需的支持（如果工具是内部或开源的）。

安全过滤

Swagger 规范中的某些对象可以被声明并保持为空，或完全被移除，即使它们本质上是 API 文档的核心。

这样做的原因是为了允许对文档本身进行额外的访问控制层。虽然不属于规范本身，但某些库可能会选择根据某种形式的身份验证/授权来允许访问文档的某些部分。

以下是两个示例

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