Swagger2.0 规范

文档内使用的关键字 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 将根据下述规范解释 RFC 2119.

Swagger 规范许可协议 The Apache License, Version 2.0.

1. 简介

Swagger™ 是用于描述和记录RESTful API的项目。

Swagger规范定义了一组描述这样的API所需的文件。 Swagger-UI项目可以使用这些文件来显示API和Swagger-Codegen来生成各种语言的客户端。 附加工具程序还可以使用生成的文件，如测试工具。

2. 版本历史

3. 定义

3.1. 路径模板

Path Templating

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

3.2. 媒体类型

Mime Types

MimeType定义分布在多个资源中。 MimeType的定义应该符合RFC 6838.

一些可能的MimeType定义的例子:

  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.3. HTTP状态码

HTTP Status Codes HTTP状态码用于指示执行操作的状态。 可用状态代码由 RFC 7231 和 IANA Status Code Registry构成.

4. 规范

4.1. 格式

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

例如，如果一个字段被称为具有数组值，则将使用JSON数组表示形式：

 
xxxxxxxxxx
{
   "field" : [...]
}

虽然API是使用JSON描述的，但它并没有将JSON输入/输出强加给API本身。

规范中的所有字段名称均为区分大小写。

Swagger的Schema暴露两种类型的字段。 具有声明名称的固定字段和模式字段。它们均声明字段名称的正则表达式模式。 只要每个都有唯一的名称，模式化的字段可以有多个出现。

4.2. 文件结构

API的Swagger表示由单个文件组成。 但是，部分定义可以分为单独的文件，由用户自行决定。 这适用于规范中的$ref字段，如下所示JSON Schema .

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

4.3. 数据类型

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

Parameter Object和Response Object使用一个额外的原始数据类型"file"将参数类型或响应设置为文件。

基本数据类型有一个可选的修饰符属性format。 Swagger使用几种已知格式更精确地定义正在使用的数据类型。 "format"属性是一个开放的"string"值属性，可以有任何值来支持文档需求。 即使这些规范未定义，仍然可以使用"email"，"uuid"等来描述格式。 不包含"format"属性的类型遵循JSON模式的定义(除了上面定义的"file"类型)。 Swagger规范定义的格式如下：

4.4. 架构

4.4.1. Swagger对象

这里开始介绍API规范的根文档对象。 它将以前的资源列表和API声明(版本1.2及更早版本)组合在一起成为一个文档。

固定字段

模式对象

4.4.2. Info对象

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

固定字段

模式对象

Info对象示例:

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

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

4.4.3. Contact对象

暴露的API的联系信息。

固定字段

模式对象

Contact对象示例:

 
xxxxxxxxxx
{
  "name": "API Support",
  "url": "http://www.swagger.io/support",
  "email": "support@swagger.io"
}

 
xxxxxxxxxx
name: API Support
url: http://www.swagger.io/support
email: support@swagger.io

4.4.4. License对象

暴露的API的许可信息。

固定字段

模式对象

License对象示例:

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

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

4.4.5. Paths对象

描述各个端点的相对路径。 该路径附加到basePath，以构造完整的URL。 由于ACL约束，路径可能为空。

模式字段

Paths对象示例

 
xxxxxxxxxx
{
  "/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"
            }
          }
        }
      }
    }
  }
}

 
xxxxxxxxxx
/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'

4.4.6. PathItem对象

描述单个路径上可用的操作。 由于ACL约束，路径项可能为空。 路径本身仍然暴露在文档查看器中，但是它们不知道哪些操作和参数可用。

固定字段

模式字段

PathItem对象示例

 
xxxxxxxxxx
{
  "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"
    }
  ]
}

 
xxxxxxxxxx
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

4.4.7. Operation对象

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

固定字段

模式对象

Operation对象示例

 
xxxxxxxxxx
{
  "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"
      ]
    }
  ]
}

 
xxxxxxxxxx
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

4.4.8. ExternalDocument对象

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

固定字段

模式对象

ExternalDocument对象示例

 
xxxxxxxxxx
{
  "description": "Find more info here",
  "url": "https://swagger.io"
}

 
xxxxxxxxxx
description: Find more info here
url: https://swagger.io

4.4.9. Parameter对象

描述单个操作参数。

唯一参数由name和location的组合定义。

有五种可能的参数类型。

• Path - 与路径模板一起使用，其中参数值实际上是操作URL的一部分。这不包括API的主机或基本路径。例如，在/items/{itemId}中，path参数是itemId。

• Query - 附加到URL的参数。例如，在/items?id=###中，查询参数为id。

• Head - 期望作为请求一部分的自定义标头。

• Body - 附加到HTTP请求的有效内容。由于只能有一个有效载荷，只能有一个参数。 body参数的名称对参数本身没有影响，仅用于文档目的。由于Form参数也在有效载荷中，因此，body和form参数不能一起存在于相同的操作中。

• Form - 用于描述HTTP请求的有效负载，当application/x-www-form-urlencoded，multipart/form-data或这两者用作请求的内容类型(在Swagger的定义中， "operation"属性)。这是可以用于发送文件的唯一参数类型，因此支持file类型。由于表单参数是在有效载荷中发送的，所以它们不能与同一操作的body参数一起声明。表格参数根据所使用的内容类型具有不同的格式(有关详细信息，请参阅http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4)：

  • application/x-www-form-urlencoded - 与Query参数的格式相似，但作为一个有效载荷。例如，foo=1&bar=swagger - foo和bar都是表单参数。这通常用于正在传输的简单参数。
  • multipart/form-data - 每个参数都在一个带有内部头部的负载中占用一个部分。例如，对于标题"Content-Disposition：form-data; name ="submit-name"参数的名称是submit-name。这种类型的表单参数更常用于文件传输。

固定字段

如果in为"body"：

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

模式字段

Parameter对象示例

Body参数

具有引用模式定义(通常用于模型定义)的body参数：

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

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

一个body参数，它是一个字符串值的数组：

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

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

其他参数

具有64位整数数组的头参数：

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

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

字符串值的路径参数：

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

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

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

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

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

文件上传的文件类型的表单数据：

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

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

4.4.10. Items对象

JSON-Schema项目对象的一个有限子集。它由不在in"body"的参数定义使用。

固定字段

模式对象

Items对象示例

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

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

 
xxxxxxxxxx
type: string
minLength: 2

一组数组，内部数组为整数，数字必须介于0到63之间(含)：

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

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

4.4.11. Responses对象

用于操作的预期响应的容器。容器将HTTP响应代码映射到预期响应。文档中预计不会涵盖所有可能的HTTP响应代码，因为它们可能不是事先知道的。但是，从文档中可以看到成功的操作响应和任何已知的错误。

"default"可以用作所有HTTP规范的默认响应对象，这些代码不在规范中。

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

固定字段

模式字段

Responses对象示例

对于成功的操作和对他人的默认响应的200个响应(意味着错误)：

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

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

4.4.12. Response对象

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

固定字段

模式对象

Response对象示例

一个复杂类型的数组的响应：

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

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

响应字符串类型：

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

 
xxxxxxxxxx
description: A simple string response
schema:
  type: string

回应头：

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

 
xxxxxxxxxx
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

没有返回值的响应：

 
xxxxxxxxxx
{
  "description": "object created"
}

 
xxxxxxxxxx
description: object created

4.4.13. Headers对象

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

模式字段

Headers对象示例

速率限制Headers：

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

 
xxxxxxxxxx
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

4.4.14. Example对象

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

模式字段

Example对象示例

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

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

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

4.4.15. Header对象

模式对象

Header对象示例

一个整数类型的简单标题：

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

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

4.4.16. Tag对象

允许将元数据添加到操作对象使用的单个标签中。在这里使用标签对象不是必须的。

固定字段

模式字段

Tag对象示例

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

 
xxxxxxxxxx
name: pet
description: Pets operations

4.4.17. Reference对象

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

引用对象是使用JSON Reference的JSON Pointer作为其值。 对于本规范，仅支持canonical dereferencing。

固定字段

Reference对象示例

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

 
xxxxxxxxxx
$ref: '#/definitions/Pet'

引用模式文件示例

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

 
xxxxxxxxxx
$ref: 'Pet.yaml'

具有嵌入式架构的相对文件示例

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

 
xxxxxxxxxx
$ref: 'definitions.yaml#/Pet'

4.4.18. Schema对象

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

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

以下属性直接从JSON模式定义中获取，并遵循相同的规范：

• $ref - 作为 JSON Reference
• format (更多细节请查看 Data Type Formats)
• title
• description (GFM syntax 可以使用富文本描述)
• default (与JSON Schema不同，值必须符合模式对象的定义类型)
• multipleOf
• maximum
• exclusiveMaximum
• minimum
• exclusiveMinimum
• maxLength
• minLength
• pattern
• maxItems
• minItems
• uniqueItems
• maxProperties
• minProperties
• required
• enum
• type

以下属性取自JSON模式定义，但其定义已调整为Swagger规范。 它们的定义与JSON Schema中的定义相同，只有原始定义引用了JSON Schema定义，才使用Schema Object定义。

• items
• allOf
• properties
• additionalProperties

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

固定字段

模式对象

组合和继承(多态)

Swagger允许使用JSON Schema的"allOf"属性组合和扩展模型定义，实际上提供模型组合。 allOf接受一个独立的验证的对象定义数组，一起构成一个对象。

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

XML建模

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

Schema对象示例

原始示例

与以前版本的Swagger不同，Schema定义也可用于描述原语和数组。

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

 
xxxxxxxxxx
type: string
format: email

简单模型

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

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

包含Map/Dictionary属性的模型

For a simple string to string mapping:

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

 
xxxxxxxxxx
type: object
additionalProperties:
  type: string

对于要映射的字符串：

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

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

Model示例

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

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

组合的模型

 
xxxxxxxxxx
{
  "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"
            }
          }
        }
      ]
    }
  }
}

 
xxxxxxxxxx
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

多态模型支持

 
xxxxxxxxxx
{
  "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"
          ]
        }
      ]
    }
  }
}

 
xxxxxxxxxx
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

4.4.19. XML 对象

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

使用数组时，XML元素名称不会被推断(用于单数/复数形式)，而'name`属性应用于添加该信息。查看预期行为的例子。

固定字段

模式对象

XML对象示例

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

非XML元素

基本字符串属性：

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

 
xxxxxxxxxx
animals:
  type: string

 
xxxxxxxxxx
<animals>...</animals>

基本字符串数组属性(wrapped默认为false)：

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

 
xxxxxxxxxx
animals:
  type: array
  items:
    type: string

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

XML名称替换

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

 
xxxxxxxxxx
animals:
  type: string
  xml:
    name: animal

 
xxxxxxxxxx
<animal>...</animal>

XML属性、前缀和命名空间

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

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

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

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

XML 数组

更改元素名称:

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

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

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

外部的 name 属性对XML没有影响:

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

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

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

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

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

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

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

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

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

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

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

影响内部和外部名称：

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

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

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

如果我们改变外部元素而不是内部元素：

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

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

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

4.4.20. Definitions对象

用于保存可由操作消耗和生成的数据类型。 这些数据类型可以是基本数据类型，数组或模型。

模式字段

Definitions对象示例

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

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

4.4.21. Parameters Definitions对象

用于保存跨操作重用的参数。 参数定义可以参考这里定义的参数。

这不定义全局操作参数。

模式字段

Parameters Definitions义对象示例

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

 
xxxxxxxxxx
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

4.4.22. Responses Definitions对象

一个对象要保持响应在操作之间重复使用。 响应定义可以参考这里定义的定义。

这不定义全局操作响应。

模式字段

Responses Definitions对象示例

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