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 支持的类型。模型使用 Schema 对象描述，该对象是 JSON Schema 草案 4 的子集。

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

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

通用名称	`类型`	`格式`	注释
整数	`整数`	`int32`	带符号的 32 位
长整型	`整数`	`int64`	带符号的 64 位
浮点数	`数值`	`浮点数`
双精度	`数值`	`双精度`
字符串	`字符串`
字节	`字符串`	`字节`	base64 编码字符
二进制	`字符串`	`二进制`	任何八位字节序列
布尔值	`布尔值`
日期	`字符串`	`日期`	由 `full-date` 定义 - RFC3339
日期时间	`字符串`	`date-time`	由 `date-time` 定义 - RFC3339
密码	`字符串`	`密码`	用于提示 UI 输入需要被遮盖。

模式

Swagger 对象

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

固定字段

字段名称	类型	描述
swagger	`字符串`	必需。指定正在使用的 Swagger 规范版本。Swagger UI 和其他客户端可以使用它来解释 API 列表。该值必须为 `"2.0"`。
info	信息对象	必需。提供有关 API 的元数据。如果需要，客户端可以使用元数据。
host	`字符串`	提供 API 的主机（名称或 IP）。这必须仅是主机，不包括方案或子路径。它可能包括端口。如果未包含 `host`，则将使用提供文档的主机（包括端口）。`host` 不支持路径模板。
basePath	`字符串`	提供 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 Schema。字段名称必须以 `x-` 开头，例如 `x-internal-id`。值可以是 `null`、基本类型、数组或对象。有关更多详细信息，请参阅供应商扩展。

信息对象

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

固定字段

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

模式对象

字段模式	类型	描述
^x-	任何	允许扩展 Swagger Schema。字段名称必须以 `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	`字符串`	联系人/组织的标识名称。
url	`字符串`	指向联系信息的 URL。必须是 URL 格式。
email	`字符串`	联系人/组织的电子邮件地址。必须是电子邮件地址格式。

模式对象

字段模式	类型	描述
^x-	任何	允许扩展 Swagger Schema。字段名称必须以 `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	`字符串`	必需。用于 API 的许可证名称。
url	`字符串`	指向 API 使用的许可证的 URL。必须是 URL 格式。

模式对象

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

模式化字段

字段模式	类型	描述
^x-	任何	允许扩展 Swagger Schema。字段名称必须以 `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	`字符串`	操作的简短摘要。为了在 swagger-ui 中获得最大的可读性，此字段应少于 120 个字符。
description	`字符串`	对操作行为的详细解释。 GFM 语法可用于富文本表示。
externalDocs	外部文档对象	此操作的其他外部文档。
operationId	`字符串`	用于标识操作的唯一字符串。该 ID 在 API 中描述的所有操作中必须是唯一的。工具和库可以使用 operationId 来唯一标识操作，因此，建议遵循常见的编程命名约定。
consumes	[`string`]	操作可以使用的 MIME 类型列表。这将覆盖 Swagger 对象中的 `consumes` 定义。可以使用空值清除全局定义。值必须按照Mime Types下的描述。
produces	[`string`]	操作可以生成的 MIME 类型列表。这将覆盖 Swagger 对象中的 `produces` 定义。可以使用空值清除全局定义。值必须按照Mime Types下的描述。
parameters	[参数对象 \| 引用对象]	适用于此操作的参数列表。如果参数已在路径项中定义，则新定义将覆盖它，但永远不能删除它。该列表不得包含重复的参数。唯一的参数由名称和位置的组合定义。该列表可以使用引用对象来链接到在Swagger 对象的参数中定义的参数。最多可以有一个“body”参数。
responses	响应对象	必需。执行此操作返回的可能响应列表。
schemes	[`string`]	操作的传输协议。值必须来自列表：`"http"`、`"https"`、`"ws"`、`"wss"`。该值将覆盖 Swagger 对象 `schemes` 定义。
deprecated	`布尔值`	声明此操作已弃用。应避免使用声明的操作。默认值为 `false`。
security	[安全要求对象]	声明此操作应用的安全方案。值列表描述了可以使用的替代安全方案（也就是说，安全要求之间存在逻辑或关系）。此定义将覆盖任何声明的顶级 `security`。要删除顶级安全声明，可以使用空数组。

模式对象

字段模式	类型	描述
^x-	任何	允许扩展 Swagger Schema。字段名称必须以 `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	`字符串`	目标文档的简短描述。 GFM 语法可用于富文本表示。
url	`字符串`	必需。目标文档的 URL。值必须是 URL 格式。

模式对象

字段模式	类型	描述
^x-	任何	允许扩展 Swagger Schema。字段名称必须以 `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 参数也位于有效负载中，因此同一操作不能同时存在 body 参数和 form 参数。
Form - 当将 application/x-www-form-urlencoded、multipart/form-data 或两者都用作请求的内容类型时（在 Swagger 的定义中，操作的 consumes 属性），用于描述 HTTP 请求的有效负载。这是唯一可以用来发送文件的参数类型，从而支持 file 类型。由于 form 参数是在有效负载中发送的，因此它们不能与同一操作的主体参数一起声明。Form 参数具有基于所用内容类型的不同格式（有关更多详细信息，请参阅http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4）
- application/x-www-form-urlencoded - 类似于查询参数格式，但作为有效负载。例如，foo=1&bar=swagger - foo 和 bar 都是 form 参数。这通常用于传输的简单参数。
- multipart/form-data - 每个参数在有效负载中都带有一个内部标头。例如，对于标头 Content-Disposition: form-data; name="submit-name"，参数的名称是 submit-name。这种类型的 form 参数更常用于文件传输。

固定字段

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

如果 in 是 "body"

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

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

字段名称	类型	描述
type	`字符串`	必需。参数的类型。由于参数不在请求正文中，因此它仅限于简单类型（即不是对象）。该值必须是 `"string"`、`"number"`、`"integer"`、`"boolean"`、`"array"` 或 `"file"` 之一。如果 `type` 是 `"file"`，则 `consumes` 必须是 `"multipart/form-data"`、`" application/x-www-form-urlencoded"` 或两者，并且参数必须 `in` `"formData"`。
format	`字符串`	用于扩展先前 `type` 的格式。更多详情请参考数据类型格式。
allowEmptyValue	`布尔值`	设置是否允许传递空值的参数。这仅对 `query` 或 `formData` 参数有效，并且允许您仅发送一个带名称的参数或一个空值的参数。默认值为 `false`。
items	Items 对象	如果 `type` 为 "array"，则为必需项。描述数组中项的类型。
collectionFormat	`字符串`	确定当 type 为 array 时数组的格式。可能的值为： `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	`数值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2。
exclusiveMaximum	`布尔值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2。
minimum	`数值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3。
exclusiveMinimum	`布尔值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3。
maxLength	`整数`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1。
minLength	`整数`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2。
pattern	`字符串`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3。
maxItems	`整数`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2。
minItems	`整数`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3。
uniqueItems	`布尔值`	请参考 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	`数值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1。

模式化字段

字段模式	类型	描述
^x-	任何	允许扩展 Swagger Schema。字段名称必须以 `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

Items 对象

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

固定字段

字段名称	类型	描述
type	`字符串`	必填。数组的内部类型。该值必须是 `"string"`、`"number"`、`"integer"`、`"boolean"` 或 `"array"` 之一。不允许使用文件和模型。
format	`字符串`	用于扩展先前 `type` 的格式。更多详情请参考数据类型格式。
items	Items 对象	如果 `type` 为 "array"，则为必需项。描述数组中项的类型。
collectionFormat	`字符串`	确定当 type 为 array 时数组的格式。可能的值为： `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	`数值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2。
exclusiveMaximum	`布尔值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2。
minimum	`数值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3。
exclusiveMinimum	`布尔值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3。
maxLength	`整数`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1。
minLength	`整数`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2。
pattern	`字符串`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3。
maxItems	`整数`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2。
minItems	`整数`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3。
uniqueItems	`布尔值`	请参考 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	`数值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1。

模式对象

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

Items 对象示例

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

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

type: string
minLength: 2

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

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

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

响应对象

操作的预期响应的容器。该容器将 HTTP 响应代码映射到预期响应。文档并不需要涵盖所有可能的 HTTP 响应代码，因为它们可能事先未知。但是，文档应涵盖成功的操作响应和任何已知的错误。

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

Responses Object 必须至少包含一个响应代码，并且应该是成功操作调用的响应。

固定字段

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

模式化字段

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

Responses 对象示例

成功操作的 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'

Response 对象

描述来自 API 操作的单个响应。

固定字段

字段名称	类型	描述
description	`字符串`	必填。响应的简短描述。 GFM 语法可用于富文本表示。
schema	模式对象	响应结构的定义。它可以是基本类型、数组或对象。如果此字段不存在，则表示不会返回任何内容作为响应的一部分。作为 Schema 对象的扩展，其根 `type` 值也可以是 `"file"`。这应附带相关的 `produces` mime 类型。
headers	Headers 对象	随响应发送的标头列表。
examples	Example 对象	响应消息的示例。

模式对象

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

Response 对象示例

复杂类型数组的响应

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

Headers 对象

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

模式化字段

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

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

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

Example 对象

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

模式化字段

字段模式	类型	描述
{mime 类型}	任何	属性的名称必须是操作的 `produces` 值之一（隐式或继承）。该值应该是一个这样的响应的示例。

Example 对象示例

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

Header 对象

字段名称	类型	描述
description	`字符串`	标头的简短描述。
type	`字符串`	必填。对象的类型。该值必须是 `"string"`、`"number"`、`"integer"`、`"boolean"` 或 `"array"` 之一。
format	`字符串`	用于扩展先前提到的 `type` 的格式。更多详情请参考数据类型格式。
items	Items 对象	如果 `type` 为 "array"，则为必需项。描述数组中项的类型。
collectionFormat	`字符串`	确定当 type 为 array 时数组的格式。可能的值为： `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	`数值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2。
exclusiveMaximum	`布尔值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2。
minimum	`数值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3。
exclusiveMinimum	`布尔值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3。
maxLength	`整数`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1。
minLength	`整数`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2。
pattern	`字符串`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3。
maxItems	`整数`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2。
minItems	`整数`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3。
uniqueItems	`布尔值`	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	`数值`	请参考 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1。

模式对象

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

Header 对象示例

一个简单的整数类型的标头

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

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

Tag 对象

允许向 Operation 对象使用的单个标签添加元数据。不强制要求每个使用的标签都有一个 Tag 对象。

固定字段

字段名称	类型	描述
name	`字符串`	必填。标签的名称。
description	`字符串`	标签的简短描述。 GFM 语法可用于富文本表示。
externalDocs	外部文档对象	此标签的其他外部文档。

模式化字段

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

Tag 对象示例

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

name: pet
description: Pets operations

Reference 对象

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

Reference 对象是一个 JSON Reference，它使用 JSON Pointer 作为其值。对于此规范，仅支持规范反向引用。

固定字段

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

Reference 对象示例

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

$ref: '#/definitions/Pet'

相对 Schema 文件示例

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

$ref: 'Pet.yaml'

具有嵌入 Schema 的相对文件示例

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

$ref: 'definitions.yaml#/Pet'

模式对象

Schema 对象允许定义输入和输出数据类型。这些类型可以是对象，也可以是基本类型和数组。此对象基于 JSON Schema Specification Draft 4，并使用其预定义的子集。除了此子集之外，此规范还提供了一些扩展，以允许更完整的文档。

有关属性的更多信息，请参阅 JSON Schema Core 和 JSON Schema Validation。除非另有说明，否则属性定义遵循此处引用的 JSON Schema 规范。

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

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

以下属性取自 JSON Schema 定义，但其定义已调整为 Swagger 规范。它们的定义与 JSON Schema 中的定义相同，只是在原始定义引用 JSON Schema 定义的地方，使用的是Schema 对象定义。

items
allOf
properties
additionalProperties

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

固定字段

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

模式对象

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

组合和继承（多态）

Swagger 允许使用 JSON Schema 的 allOf 属性组合和扩展模型定义，从而提供模型组合。allOf 接受一个对象定义数组，这些对象定义被独立验证，但一起构成一个对象。

虽然组合提供了模型的可扩展性，但它并不暗示模型之间的层次结构。为了支持多态，Swagger 添加了对 discriminator 字段的支持。使用时，discriminator 将是用于决定使用哪个模式定义来验证模型结构的属性的名称。因此，discriminator 字段必须是一个必填字段。所选属性的值必须是在 definitions 属性下给模型的友好名称。因此，没有给定 id 的内联模式定义不能在多态中使用。

XML 建模

当将 JSON 定义转换为 XML 时，xml 属性允许额外的定义。XML 对象包含有关可用选项的其他信息。

Schema 对象示例

原始示例

与之前版本的 Swagger 不同，Schema 定义也可以用来描述原始类型和数组。

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

带有 Map/Dictionary 属性的模型

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

{
  "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	`字符串`	替换用于描述的模式属性的元素/属性的名称。在 Items 对象（`items`）中定义时，它将影响列表中单个 XML 元素的名称。当与 `type` 为 `array`（在 `items` 之外）一起定义时，它将影响包装元素，并且仅当 `wrapped` 为 `true` 时才会影响。如果 `wrapped` 为 `false`，则会忽略它。
namespace	`字符串`	命名空间定义的 URL。值应该采用 URL 的形式。
prefix	`字符串`	用于 name 的前缀。
attribute	`布尔值`	声明属性定义转换为属性而不是元素。默认值为 `false`。
wrapped	`布尔值`	可能仅用于数组定义。表示数组是包装的（例如，`<books><book/><book/></books>`）还是未包装的（`<book/><book/>`）。默认值为 `false`。该定义仅在与 `type` 为 `array`（在 `items` 之外）一起定义时生效。

模式对象

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

XML 对象示例

XML 对象定义的示例包含在Schema 对象的属性定义中，并带有其 XML 表示形式的示例。

没有 XML 元素

基本字符串属性

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

animals:
  type: string

<animals>...</animals>

基本字符串数组属性（wrapped 默认为 false）

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

animals:
  type: array
  items:
    type: string

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

XML 名称替换

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

animals:
  type: string
  xml:
    name: animal

<animal>...</animal>

XML 属性、前缀和命名空间

在此示例中，显示了一个完整的模型定义。

{
  "Person": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int32",
        "xml": {
          "attribute": true
        }
      },
      "name": {
        "type": "string",
        "xml": {
          "namespace": "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}	模式对象	单个定义，将“name”映射到它定义的模式。

Definitions 对象示例

{
  "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}	参数对象	单个参数定义，将“name”映射到它定义的参数。

Parameters Definition 对象示例

{
  "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}	Response 对象	单个响应定义，将“name”映射到它定义的响应。

Responses Definitions 对象示例

{
  "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}	安全方案对象	单个安全方案定义，将“name”映射到它定义的方案。

Security Definitions 对象示例

{
  "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	`字符串`	任何	必需。安全方案的类型。有效值为 `"basic"`、`"apiKey"` 或 `"oauth2"`。
description	`字符串`	任何	安全方案的简短描述。
name	`字符串`	`apiKey`	必需。要使用的标头或查询参数的名称。
in	`字符串`	`apiKey`	必需 API 密钥的位置。有效值为 `"query"` 或 `"header"`。
flow	`字符串`	`oauth2`	必需。OAuth2 安全方案使用的流程。有效值为 `"implicit"`、`"password"`、`"application"` 或 `"accessCode"`。
authorizationUrl	`字符串`	`oauth2` (`"implicit"`, `"accessCode"`)	必需。此流程要使用的授权 URL。这应该采用 URL 的形式。
tokenUrl	`字符串`	`oauth2` (`"password"`, `"application"`, `"accessCode"`)	必需。此流程要使用的令牌 URL。这应该采用 URL 的形式。
scopes	Scopes 对象	`oauth2`	必需。OAuth2 安全方案的可用范围。

模式化字段

字段名称	类型	描述
^x-	任何	允许扩展 Swagger Schema。字段名称必须以 `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

Scopes 对象

列出 OAuth2 安全方案的可用范围。

模式化字段

字段模式	类型	描述
{name}	`字符串`	将范围的名称映射到其简短描述（作为属性的值）。

模式对象

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

Scopes 对象示例

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

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

安全要求对象

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

每个属性使用的名称必须与 Security Definitions 中声明的安全方案相对应。

模式化字段

字段模式	类型	描述
{name}	[`string`]	每个名称必须与 Security Definitions 中声明的安全方案相对应。如果安全方案的类型为 `"oauth2"`，则该值是执行所需的范围名称列表。对于其他安全方案类型，数组必须为空。

安全要求对象示例

非 OAuth2 安全要求

{
  "api_key": []
}

api_key: []

OAuth2 安全要求

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

petstore_auth:
- write:pets
- read:pets

规范扩展

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

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

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

安全筛选

Swagger 规范中的某些对象可能会被声明为空，或者完全被删除，即使它们本质上是 API 文档的核心。

其背后的原因是允许对文档本身进行额外的访问控制层。虽然不是规范本身的一部分，但某些库可能会选择允许基于某种形式的身份验证/授权来访问文档的某些部分。

以下是两个示例

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