The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

本文档中的关键词 "MUST"、"MUST NOT"、"REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、"RECOMMENDED"、"NOT RECOMMENDED"、"MAY"和 "OPTIONAL"， 当且仅当它们以全大写字母出现时，应按照 BCP 14 RFC2119 RFC8174 中的描述进行解释。

译者注 中文没有大小写之分, 将使用 加粗 和保留英文的方式来标出这些关键词。

This document is licensed under The Apache License, Version 2.0.

本文档遵循 The Apache License, Version 2.0 许可证.

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

OpenAPI 规范 (OAS) ，是一个定义标准的、与具体编程语言无关的RESTful API的规范。 本规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。 一个良好定义的 API 可以使得使用者非常轻松地理解并与之交互而不需要了解它的实现逻辑。

An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

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

• 定义 Definitions
  • OpenAPI 文档 OpenAPI Document
  • 路径模板 Path Templating
  • 媒体类型 Media Types
  • HTTP 状态码 HTTP Status Codes
• 规范 Specification
  • 版本 Versions
  • 格式 Format
  • 文档结构 Document Structure
  • 数据类型 Data Types
  • 富文本格式 Rich Text Formatting
  • 相对引用 Relative References In URLs
  • Schema
    • OpenAPI Object
    • Info Object
    • Contact Object
    • License Object
    • Server Object
    • Server Variable Object
    • Components Object
    • Paths Object
    • Path Item Object
    • Operation Object
    • External Documentation Object
    • Parameter Object
    • Request Body Object
    • Media Type Object
    • Encoding Object
    • Responses Object
    • Response Object
    • Callback Object
    • Example Object
    • Link Object
    • Header Object
    • Tag Object
    • Reference Object
    • Schema Object
    • Discriminator Object
    • XML Object
    • Security Scheme Object
    • OAuth Flows Object
    • OAuth Flow Object
    • Security Requirement Object
  • 扩展规范 Specification Extensions
  • 安全过滤 Security Filtering
• 附录 A: 修订历史 Appendix A: Revision History

译者注: 关于 Schema 目前没有一个很好的中文翻译, 故本文档所有出现 Schema 的地方都将不做翻译。 读者可以根据自己理解和偏好自行脑译成架构, 结构, 模型, 模式 等等中文术语。

A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.

一份（或多份）用来定义或描述API的文档。 一个OpenAPI定义使用并符合OpenAPI规范。

Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.

路径模板化是指使用模板表达式将URL路径的一部分标记为可替换的, 这些可替换的部分称为路径参数。 一个模板表达式代表一个路径参数, 用大括号({})包裹。

Each template expression in the path MUST correspond to a path parameter that is included in the Path Item itself and/or in each of the Path Item's Operations.

路径中的每个模板表达式必须 (MUST) 对应一个路径参数， 该参数包含在路径项本身和(或)路径项的每个操作中。

Media type definitions are spread across several resources. The media type definitions SHOULD be in compliance with RFC6838.

媒体类型定义分散于多处。 媒体类型定义应当 (SHOULD) 符合 RFC6838 。

Some examples of possible media type definitions:

以下是一些媒体类型定义的示例：

  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

The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are defined by RFC7231 and registered status codes are listed in the IANA Status Code Registry.

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

The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.

OpenAPI规范使用 Semantic Versioning 2.0.0 进行版本管理，并遵循semver规范。

The major.minor portion of the semver (for example 3.0) SHALL designate the OAS feature set. Typically, .patch versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.0.0 and 3.0.1 for example.

semver的 major.minor (magor:主版本号, minor:次版本号)部分（例如3.0）应当( SHALL )被用来标记OAS的功能变动。 通常，.patch (patch:修订号)版本解决的是本文档中的错误，而不是功能变动。 支持 OAS 3.0 的工具应该( SHOULD )与所有 OAS 3.0.* 版本兼容。 工具不需要( ** SHOULD NOT ** )关心补丁版本的变动，例如在 3.0.0 和 3.0.1 之间对工具来说应该没有任何区别。

Each new minor version of the OpenAPI Specification SHALL allow any OpenAPI document that is valid against any previous minor version of the Specification, within the same major version, to be updated to the new Specification version with equivalent semantics. Such an update MUST only require changing the openapi property to the new minor version.

OpenAPI规范 的每一个新的次要版本都应该( SHALL )兼容同一主要版本的任何以前的次要版本的规范， 以便更新到具有同等语义的新规范版本。 次要版本的升级必须 ( MUST ) 只需要更改openapi 属性到新的次要版本即可, 不需要修改其他内容。

For example, a valid OpenAPI 3.0.2 document, upon changing its openapi property to 3.1.0, SHALL be a valid OpenAPI 3.1.0 document, semantically equivalent to the original OpenAPI 3.0.2 document. New minor versions of the OpenAPI Specification MUST be written to ensure this form of backward compatibility.

例如，一个有效的 OpenAPI 3.0.2 文档，在将其 openapi 属性更改为 3.1.0 后，将( SHALL )成为一个有效的 OpenAPI 3.1.0 文档，在语义上等同于原来的 OpenAPI 3.0.2 文档。 在制定新的次要版本时, 必须 ( MUST ) 确保这种形式的向后兼容性。

An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)

与 OAS 3.*.* 兼容的OpenAPI文档包含一个必需的 openapi 字段，该字段指定了它所使用的OAS的语义版本。 (OAS 2.0 文档包含一个名为 swagger 和值为 "2.0" 的顶层版本字段。)

An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.

一份符合OpenAPI规范的OpenAPI文档是一个JSON对象，可以使用JSON或YAML格式编写。

For example, if a field has an array value, the JSON array representation will be used:

例如，如果一个字段有一个数组值，将使用JSON数组表示为:

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

All field names in the specification are case sensitive. This includes all fields that are used as keys in a map, except where explicitly noted that keys are case insensitive.

规范中的所有字段名都是 区分大小写 的，这包括所有在map中作为键(key)的字段，除非明确指出键 不 区分大小写。

The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.

schema定义了两种类型的字段: 固定字段(Fixed fields)和模式化字段(Patterned fields)。 固定字段的字段名是确定的，模式字段的字段名需要符合一定的格式(regex pattern)。

Patterned fields MUST have unique names within the containing object.

如果一个对象里有模式化字段(Patterned fields)，那么在这个对象里的模式化字段(Patterned fields)的名字必须( MUST )唯一, 不能有重复。

In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:

为了保持 YAML 和 JSON 格式之间的相互转换能力，推荐使用YAML 1.2 版本以及需要遵守以下一些额外的限制:

• Tags MUST be limited to those allowed by the JSON Schema ruleset.
• Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.

• 标签(Tags)必须( MUST )限制在 JSON Schema ruleset 所允许的范围内。
• 在 YAML maps 中使用的键(key)必须时符合 YAML Failsafe schema ruleset 定义的纯字符串(scalar string)。

Note: While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.

Note: 虽然API可以由OpenAPI文档以YAML或JSON格式定义，但API请求和响应体和其他内容并不是必须是JSON或YAML, 可以是任何格式。

An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.

一个OpenAPI文档可以( MAY )由一个单一的文档组成，也可以由用户自行决定分为多个相互关联的部分(拆分成多个文档)。 在后一种情况下，必须在规范中使用$ref字段来引用那些来自 JSON Schema 定义的部分。

It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.

建议( RECOMMENDED )将 OpenAPI 根文档命名为：openapi.json 或 openapi.yaml。

Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00. Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. null is not supported as a type (see nullable for an alternative solution). Models are defined using the Schema Object, which is an extended subset of JSON Schema Specification Wright Draft 00.

OAS中的原始数据类型基于JSON Schema Specification Wright Draft 00定义的类型。 整数也作为一种类型来支持，并且被定义为是没有分数或指数部分的JSON数字。 null 不是数据类型（参见nullable以获得替代解决方案）。 模型(Models)使用Schema Object来定义，它是JSON Schema Specification Wright Draft 00的扩展子集。

Primitives have an optional modifier property: format. OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the format property is an open string-valued property, and can have any value. Formats such as "email", "uuid", and so on, MAY be used even though undefined by this specification. Types that are not accompanied by a format property follow the type definition in the JSON Schema. Tools that do not recognize a specific format MAY default back to the type alone, as if the format is not specified.

原始类型都有一个可选的修饰符属性：format。 OAS 使用几种已知的格式来指明数据类型的具体格式。 然而，为了支持文档需求，format 属性是一个开放的字符串值属性，可以是任何值。 格式如 "email", "uuid" 等，即使本规范没有定义，也可以( MAY )使用。 没有附带 format 属性的类型遵循 JSON Schema 中的类型定义。 工具如果遇到无法识别的特定格式, 可以按默认的类型来处理，就像没有指定格式一样。

The formats defined by the OAS are:

OAS已定义的格式有：

Throughout the specification description fields are noted as supporting CommonMark markdown formatting. Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.

在整个规范中，description 字段都被注明为支持CommonMark markdown格式。 当OpenAPI工具渲染富文本时，它必须至少支持 CommonMark 0.27 所描述的markdown语法。 工具可以( MAY )选择忽略一些CommonMark的功能来解决安全问题。

Unless specified otherwise, all properties that are URLs MAY be relative references as defined by RFC3986. Relative references are resolved using the URLs defined in the Server Object as a Base URI.

除非另有规定，否则所有作为 URL 的属性都可以(MAY)是 RFC3986 定义的相对引用。 相对引用使用 Server Object 中定义的URL作为基础URI进行解析。

Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.

在$ref 中使用的相对引用按照 JSON Reference 处理，使用当前文档的URL作为基础URI。也请参见Reference Object。

In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.

在下面的描述中，如果一个字段没有明确的 REQUIRED 或用 MUST 或 SHALL 来描述，它可以被认为是可选的( OPTIONAL )。

This is the root document object of the OpenAPI document.

这个是 OpenAPI文档 的根对象。

The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.

该对象提供了关于API的元数据。如果需要的话，这些元数据可以 (MAY) 被客户使用，也可以 (MAY) 在编辑或文档生成工具中显示，以方便客户使用。

This object MAY be extended with Specification Extensions.

这个对象是个可扩展对象, 可以 (MAY) 按照 Specification Extensions 中的说明进行扩展。

{
  "title": "Sample Pet Store App",
  "description": "This is a sample server for a pet store.",
  "termsOfService": "http://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "http://www.example.com/support",
    "email": "support@example.com"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
  name: API Support
  url: http://www.example.com/support
  email: support@example.com
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

{
  "title": "宠物商店APP例子",
  "description": "这是一个宠物商店APP例子的服务端。",
  "termsOfService": "http://example.com/terms/",
  "contact": {
    "name": "API支持",
    "url": "http://www.example.com/support",
    "email": "support@example.com"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

title: 宠物商店APP例子
description: 这是一个宠物商店APP例子的服务端。
termsOfService: http://example.com/terms/
contact:
  name: API 支持
  url: http://www.example.com/support
  email: support@example.com
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

Contact information for the exposed API.

API的联系信息

This object MAY be extended with Specification Extensions.

这个对象是个可扩展对象, 可以 (MAY) 按照 Specification Extensions 中的说明进行扩展。

{
  "name": "API Support",
  "url": "http://www.example.com/support",
  "email": "support@example.com"
}

name: API Support
url: http://www.example.com/support
email: support@example.com

{
  "name": "API支持",
  "url": "http://www.example.com/support",
  "email": "support@example.com"
}

name: API支持,
url: http://www.example.com/support
email: support@example.com

License information for the exposed API.

API的证书信息。

This object MAY be extended with Specification Extensions.

这个对象是个可扩展对象, 可以 (MAY) 按照 Specification Extensions 中的说明进行扩展。

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

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

An object representing a Server.

表示一个服务器的对象。

This object MAY be extended with Specification Extensions.

这个对象是个可扩展对象, 可以 (MAY) 按照 Specification Extensions 中的说明进行扩展。

A single server would be described as:

单个服务器例子:

{
  "url": "https://development.gigantic-server.com/v1",
  "description": "Development server"
}

url: https://development.gigantic-server.com/v1
description: Development server

{
  "url": "https://development.gigantic-server.com/v1",
  "description": "开发服务器"
}

url: https://development.gigantic-server.com/v1
description: 开发服务器

The following shows how multiple servers can be described, for example, at the OpenAPI Object's servers:

多个服务器例子:

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "开发服务器"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "预演服务器"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "产品服务器"
    }
  ]
}

servers:
- url: https://development.gigantic-server.com/v1
  description: 开发服务器
- url: https://staging.gigantic-server.com/v1
  description: 预演服务器
- url: https://api.gigantic-server.com/v1
  description: 产品服务器

The following shows how variables can be used for a server configuration:

URL模板和变量使用例子:

{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}

servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
  description: The production API server
  variables:
    username:
      # note! no enum here means it is an open value
      default: demo
      description: this value is assigned by the service provider, in this example `gigantic-server.com`
    port:
      enum:
        - '8443'
        - '443'
      default: '8443'
    basePath:
      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
      default: v2

{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "产品API服务器",
      "variables": {
        "username": {
          "default": "demo",
          "description": "此变量由`gigantic-server.com`的服务提供者指定, 默认值是`demo`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}

servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
  description: 产品API服务器
  variables:
    username:
      # 注意! 没有指定枚举值表示它是个开放的值
      default: demo
      description: 此变量由`gigantic-server.com`的服务提供者指定, 默认值是`demo`
    port:
      enum:
        - '8443'
        - '443'
      default: '8443'
    basePath:
      # 没有罗列枚举值, 表示这是一个开放值, 意味着有机会使用服务提供者分配的特殊基本路径，默认为`v2`。
      default: v2

An object representing a Server Variable for server URL template substitution.

代表一个服务器变量的对象，用于服务器URL模板替换。

This object MAY be extended with Specification Extensions.

这个对象是个可扩展对象, 可以 (MAY) 按照 Specification Extensions 中的说明进行扩展。

Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.

为OAS的不同方面定义了一组可重复使用的对象。 在Components对象中定义的所有对象都不会对API产生直接的影响，除非它们明确地被Components对象之外的属性引用。

All the fixed fields declared above are objects that MUST use keys that match the regular expression: ^[a-zA-Z0-9\.\-_]+$.

Field Name Examples:

上面声明的所有固定字段的key都必须(MUST)符合以下正则表达式: ^[a-zA-Z0-9\.\-_]+$。

譬如:

User
User_1
User_Name
user-name
my.org.User

"components": {
  "schemas": {
    "GeneralError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "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"
        }
      }
    }
  },
  "parameters": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "number of items to skip",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "Entity not found."
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  },
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "http://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "modify pets in your account",
            "read:pets": "read your pets"
          }
        }
      }
    }
  }
}

components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          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
  parameters:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: max records to return
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.
    GeneralError:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
    petstore_auth:
      type: oauth2
      flows: 
        implicit:
          authorizationUrl: http://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets

"components": {
  "schemas": {
    "GeneralError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "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"
        }
      }
    }
  },
  "parameters": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "跳过多少个items, 相当于SQL中的offset",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "最多返回多少条记录, 相当于SQL的limit",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "找不到实体。"
    },
    "IllegalInput": {
      "description": "非法的输入。"
    },
    "GeneralError": {
      "description": "一般错误",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  },
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "http://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "修改你的宠物信息",
            "read:pets": "读取你的重复信息"
          }
        }
      }
    }
  }
}

components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          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
  parameters:
    skipParam:
      name: skip
      in: query
      description: 跳过多少个items, 相当于SQL中的offset
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: 最多返回多少条记录, 相当于SQL的limit
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: 找不到实体。
    IllegalInput:
      description: 非法的输入。
    GeneralError:
      description: 一般错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
    petstore_auth:
      type: oauth2
      flows: 
        implicit:
          authorizationUrl: http://example.org/api/oauth/dialog
          scopes:
            write:pets: 修改你的宠物信息
            read:pets: 读取你的重复信息

Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the Server Object in order to construct the full URL.
The Paths MAY be empty, due to ACL constraints.

保存了各个端点(endpoints)及其操作(operations)的相对路径。 该路径会追加到 Server Object 的URL上从而形成完整的访问URL。 由于 ACL 限制 ，路径可能(MAY)为空。

This object MAY be extended with Specification Extensions.

这个对象是个可扩展对象, 可以 (MAY) 按照 Specification Extensions 中的说明进行扩展。

Assuming the following paths, the concrete definition, /pets/mine, will be matched first if used:

假设使用以下路径，如果使用具体的定义(非模式化)，/pets/mine，将首先匹配。

  /pets/{petId}
  /pets/mine

The following paths are considered identical and invalid:

以下路径模板会被认为不合法:

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

The following may lead to ambiguous resolution:

以下路径模板会被认为不合法:

  /{entity}/me
  /books/{id}

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

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

{
  "/pets": {
    "get": {
      "description": "返回用户当前访问的系统的所有宠物。",
      "responses": {
        "200": {          
          "description": "宠物列表",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}

/pets:
  get:
    description: 返回用户当前访问的系统的所有宠物。
    responses:
      '200':
        description: 宠物列表
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/pet'

Describes the operations available on a single path. A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.

描述单个路径上可用的操作。由于ACL的限制，路径项可以(MAY)是空字符串。路径本身仍然会暴露给文档浏览者，但他们不会知道哪些操作和参数是可用的。

This object MAY be extended with Specification Extensions.

这个对象是个可扩展对象, 可以 (MAY) 按照 Specification Extensions 中的说明进行扩展。

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

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*' :
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        'text/html':
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  schema:
    type: array
    items:
      type: string  
  style: simple

{
  "get": {
    "description": "根据ID返回宠物",
    "summary": "根据查找宠物",
    "operationId": "getPetsById",
    "responses": {
      "200": {
        "description": "宠物响应",
        "content": {
          "*/*": {
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        }
      },
      "default": {
        "description": "错误信息",
        "content": {
          "text/html": {
            "schema": {
              "$ref": "#/components/schemas/ErrorModel"
            }
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "宠物ID",
      "required": true,
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "style": "simple"
    }
  ]
}

get:
  description: 根据ID返回宠物
  summary: 根据查找宠物
  operationId: getPetsById
  responses:
    '200':
      description: 宠物响应
      content:
        '*/*' :
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: 错误信息
      content:
        'text/html':
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
- name: id
  in: path
  description: 宠物ID
  required: true
  schema:
    type: array
    items:
      type: string  
  style: simple

Describes a single API operation on a path.

描述一个路径下的某个API操作。

This object MAY be extended with Specification Extensions.

这个对象是个可扩展对象, 可以 (MAY) 按照 Specification Extensions 中的说明进行扩展。

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

tags:
- pet
summary: Updates a pet in the store with form data
operationId: updatePetWithForm
parameters:
- name: petId
  in: path
  description: ID of pet that needs to be updated
  required: true
  schema:
    type: string
requestBody:
  content:
    'application/x-www-form-urlencoded':
      schema:
       properties:
          name: 
            description: Updated name of the pet
            type: string
          status:
            description: Updated status of the pet
            type: string
       required:
         - status
responses:
  '200':
    description: Pet updated.
    content: 
      'application/json': {}
      'application/xml': {}
  '405':
    description: Method Not Allowed
    content: 
      'application/json': {}
      'application/xml': {}
security:
- petstore_auth:
  - write:pets
  - read:pets

{
  "tags": [
    "pet"
  ],
  "summary": "以表单形式提交数据, 更新宠物信息",
  "operationId": "updatePetWithForm",
  "parameters": [
    {
      "name": "petId",
      "in": "path",
      "description": "需要更新的宠物的ID",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "name": { 
              "description": "更新后的宠物名称",
              "type": "string"
            },
            "status": {
              "description": "更新后的宠物状态",
              "type": "string"
            }
          },
          "required": ["status"] 
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "宠物信息已更新",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    },
    "405": {
      "description": "不支持此HTTP方法",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    }
  },
  "security": [
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ]
}

tags:
- pet
summary: 以表单形式提交数据, 更新宠物信息
operationId: updatePetWithForm
parameters:
- name: petId
  in: path
  description: 需要更新的宠物的ID
  required: true
  schema:
    type: string
requestBody:
  content:
    'application/x-www-form-urlencoded':
      schema:
       properties:
          name: 
            description: 更新后的宠物名称
            type: string
          status:
            description: 更新后的宠物状态
            type: string
       required:
         - status
responses:
  '200':
    description: 宠物信息已更新
    content: 
      'application/json': {}
      'application/xml': {}
  '405':
    description: 不支持此HTTP方法
    content: 
      'application/json': {}
      'application/xml': {}
security:
- petstore_auth:
  - write:pets
  - read:pets

Allows referencing an external resource for extended documentation.

可以引用一个外部资源作为扩展说明文档。

This object MAY be extended with Specification Extensions.

这个对象是个可扩展对象, 可以 (MAY) 按照 Specification Extensions 中的说明进行扩展。

{
  "description": "Find more info here",
  "url": "https://example.com"
}

description: Find more info here
url: https://example.com

{
  "description": "更多信息请访问此网址",
  "url": "https://example.com"
}

description: 更多信息请访问此网址
url: https://example.com

Describes a single operation parameter.

描述一个操作参数。

A unique parameter is defined by a combination of a name and location.

一个参数的唯一性由 name 和 location 的组合来确定。

There are four possible parameter locations specified by the in field:

• path - Used together with Path Templating, where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
• query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
• header - Custom headers that are expected as part of the request. Note that RFC7230 states header names are case insensitive.
• cookie - Used to pass a specific cookie value to the API.

in字段的值是参数的位置, 有4种值：

• path - 路径参数, 与 Path Templating 一起使用，当参数的值是操作的URL的一部分时使用，但是不包含主机地址或基础路径。比如在路径 /items/{itemId} 中，路径参数是 itemId。
• query - 查询参数, 追加在URL地址之后的参数，比如 /items?id=### 中，查询参数是 id。
• header - 请求头参数, 请求中使用的自定义请求头，注意在 RFC7230 中规定，请求头的命名是不区分大小写的。
• cookie - 用于传递特定的cookie值。

The rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a schema and style can describe the structure and syntax of the parameter.

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

Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The examples field is mutually exclusive of the example field. Furthermore, if referencing a schema that contains an example, the examples value SHALL override the example provided by the schema.

For more complex scenarios, the content property can define the media type and schema of the parameter. A parameter MUST contain either a schema property, or a content property, but not both. When example or examples are provided in conjunction with the schema object, the example MUST follow the prescribed serialization strategy for the parameter.

对于更复杂的场景，content属性可以定义参数的媒体类型和对应的结构(schema)。 一个参数必须(MUST)且只能包含schema和content属性中的一个。 当example 或examples在schema对象有定义时，示例必须(MUST)符合参数的序列化策略。

字段名 | 类型 | 描述 ---|:---:|--- content | Map[`string`, [Media Type Object](#mediaTypeObject)] | 一个定义参数如何呈现的键值对映射。键是媒体类型，值是对应媒体类型的描述，此键值对只能(**MUST**)包含一组键值对。

In order to support common ways of serializing simple parameters, a set of style values are defined.

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

Assume a parameter named color has one of the following values:

假设color参数包含如下之一的值：

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

The following table shows examples of rendering differences for each value.

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

This object MAY be extended with Specification Extensions.

这个对象是个可扩展对象, 可以 (MAY) 按照 Specification Extensions 中的说明进行扩展。

A header parameter with an array of 64 bit integer numbers:

一个数组元素为64位整数的请求头参数：

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

name: token
in: header
description: token to be passed as a header
required: true
schema:
  type: array
  items:
    type: integer
    format: int64
style: simple

{
  "name": "token",
  "in": "header",
  "description": "通过HTTP header提交的token参数",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "integer",
      "format": "int64"
    }
  },
  "style": "simple"
}

name: token
in: header
description: 通过HTTP header提交的token参数
required: true
schema:
  type: array
  items:
    type: integer
    format: int64
style: simple

A path parameter of a string value:

一个值类型为字符串的路径参数：

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

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

{
  "name": "username",
  "in": "path",
  "description": "用户名",
  "required": true,
  "schema": {
    "type": "string"
  }
}

name: username
in: path
description: 用户名
required: true
schema:
  type: string

An optional query parameter of a string value, allowing multiple values by repeating the query parameter:

一个值类型为字符串的可选查询参数，允许通过通过重复参数来传递多个值：

{
  "name": "id",
  "in": "query",
  "description": "ID of the object to fetch",
  "required": false,
  "schema": {
    "type": "array",
    "items": {
      "type": "string"
    }
  },
  "style": "form",
  "explode": true
}

name: id
in: query
description: ID of the object to fetch
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true

{
  "name": "id",
  "in": "query",
  "description": "对象ID",
  "required": false,
  "schema": {
    "type": "array",
    "items": {
      "type": "string"
    }
  },
  "style": "form",
  "explode": true
}

name: id
in: query
description: 对象ID
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true

A free-form query parameter, allowing undefined parameters of a specific type:

一个任意格式的查询参数，允许使用指定类型的未定义参数：

{
  "in": "query",
  "name": "freeForm",
  "schema": {
    "type": "object",
    "additionalProperties": {
      "type": "integer"
    }
  },
  "style": "form"
}

in: query
name: freeForm
schema:
  type: object
  additionalProperties:
    type: integer
style: form

{
  "in": "query",
  "name": "freeForm",
  "schema": {
    "type": "object",
    "additionalProperties": {
      "type": "integer"
    }
  },
  "style": "form"
}

in: query
name: freeForm
schema:
  type: object
  additionalProperties:
    type: integer
style: form

A complex parameter using content to define serialization:

使用content定义序列化方法的复杂参数：

{
  "in": "query",
  "name": "coordinates",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "lat",
          "long"
        ],
        "properties": {
          "lat": {
            "type": "number"
          },
          "long": {
            "type": "number"
          }
        }
      }
    }
  }
}

in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number

{
  "in": "query",
  "name": "coordinates",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "lat",
          "long"
        ],
        "properties": {
          "lat": {
            "type": "number"
          },
          "long": {
            "type": "number"
          }
        }
      }
    }
  }
}

in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number

Describes a single request body.

描述单个请求消息体。

This object MAY be extended with Specification Extensions.

这个对象是个可扩展对象, 可以 (MAY) 按照 Specification Extensions 中的说明进行扩展。

A request body with a referenced model definition.

请求消息体参数是一个引用的例子:

{
  "description": "user to add to the system",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User Example", 
            "externalValue": "http://foo.bar/examples/user-example.json"
          } 
        }
    },
    "application/xml": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User example in XML",
            "externalValue": "http://foo.bar/examples/user-example.xml"
          }
        }
    },
    "text/plain": {
      "examples": {
        "user" : {
            "summary": "User example in Plain text",
            "externalValue": "http://foo.bar/examples/user-example.txt" 
        }
      } 
    },
    "*/*": {
      "examples": {
        "user" : {
            "summary": "User example in other format",
            "externalValue": "http://foo.bar/examples/user-example.whatever"
        }
      }
    }
  }
}

description: user to add to the system
content: 
  'application/json':
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User Example
        externalValue: 'http://foo.bar/examples/user-example.json'
  'application/xml':
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User Example in XML
        externalValue: 'http://foo.bar/examples/user-example.xml'
  'text/plain':
    examples:
      user:
        summary: User example in text plain format
        externalValue: 'http://foo.bar/examples/user-example.txt'
  '*/*':
    examples:
      user: 
        summary: User example in other format
        externalValue: 'http://foo.bar/examples/user-example.whatever'

{
  "description": "添加用户",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "用户例子(JSON格式)", 
            "externalValue": "http://foo.bar/examples/user-example.json"
          } 
        }
    },
    "application/xml": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "用户例子(XML格式)",
            "externalValue": "http://foo.bar/examples/user-example.xml"
          }
        }
    },
    "text/plain": {
      "examples": {
        "user" : {
            "summary": "用户例子(纯文本格式)",
            "externalValue": "http://foo.bar/examples/user-example.txt" 
        }
      } 
    },
    "*/*": {
      "examples": {
        "user" : {
            "summary": "用户例子(其他格式)",
            "externalValue": "http://foo.bar/examples/user-example.whatever"
        }
      }
    }
  }
}

description: 添加用户
content: 
  'application/json':
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: 用户例子(JSON格式)
        externalValue: 'http://foo.bar/examples/user-example.json'
  'application/xml':
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: 用户例子(XML格式)
        externalValue: 'http://foo.bar/examples/user-example.xml'
  'text/plain':
    examples:
      user:
        summary: 用户例子(纯文本格式)
        externalValue: 'http://foo.bar/examples/user-example.txt'
  '*/*':
    examples:
      user: 
        summary: 用户例子(其他格式)
        externalValue: 'http://foo.bar/examples/user-example.whatever'

A body parameter that is an array of string values:

请求消息体参数是一个字符串数组的例子:

{
  "description": "user to add to the system",
  "content": {
    "text/plain": {
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

description: user to add to the system
required: true
content:
  text/plain:
    schema:
      type: array
      items:
        type: string

{
  "description": "批量添加用户",
  "content": {
    "text/plain": {
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

description: 批量添加用户
required: true
content:
  text/plain:
    schema:
      type: array
      items:
        type: string

Each Media Type Object provides schema and examples for the media type identified by its key.

每种媒体类型都有一个唯一的key作为标识, 每个媒体类型对象定义了它的结构(schema)和提供了相应的示例。

This object MAY be extended with Specification Extensions.

这个对象是个可扩展对象, 可以 (MAY) 按照 Specification Extensions 中的说明进行扩展。

{
  "application/json": {
    "schema": {
         "$ref": "#/components/schemas/Pet"
    },
    "examples": {
      "cat" : {
        "summary": "An example of a cat",
        "value": 
          {
            "name": "Fluffy",
            "petType": "Cat",
            "color": "White",
            "gender": "male",
            "breed": "Persian"
          }
      },
      "dog": {
        "summary": "An example of a dog with a cat's name",
        "value" :  { 
          "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        },
      "frog": {
          "$ref": "#/components/examples/frog-example"
        }
      }
    }
  }
}

application/json: 
  schema:
    $ref: "#/components/schemas/Pet"
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: "#/components/examples/frog-example"

{
  "application/json": {
    "schema": {
         "$ref": "#/components/schemas/Pet"
    },
    "examples": {
      "cat" : {
        "summary": "这是一只猫的例子",
        "value": 
          {
            "name": "Fluffy",
            "petType": "Cat",
            "color": "White",
            "gender": "male",
            "breed": "Persian"
          }
      },
      "dog": {
        "summary": "这是一只狗的例子, 给它起了一个猫的名字",
        "value" :  { 
          "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        },
      "frog": {
          "$ref": "#/components/examples/frog-example"
        }
      }
    }
  }
}

application/json: 
  schema:
    $ref: "#/components/schemas/Pet"
  examples:
    cat:
      summary: 这是一只猫的例子
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: 这是一只狗的例子, 给它起了一个猫的名字
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: "#/components/examples/frog-example"

In contrast with the 2.0 specification, file input/output content in OpenAPI is described with the same semantics as any other schema type. Specifically:

相对于2.0的规范，在OpenAPI规范中file内容的上传与下载与其他类型一样使用相同的语法来描述。特别是:

# content transferred with base64 encoding
schema:
  type: string
  format: base64

# content transferred in binary (octet-stream):
schema:
  type: string
  format: binary

# 通过base64编码进行传输
schema:
  type: string
  format: base64

# 通过binary(二进制数据流)编码进行传输:
schema:
  type: string
  format: binary

These examples apply to either input payloads of file uploads or response payloads.

这些示例同时适用于文件上传和下载。

A requestBody for submitting a file in a POST operation may look like the following example:

一个使用POST操作提交文件的requestBody看起来像下面这样：

requestBody:
  content:
    application/octet-stream:
      schema:
        # a binary file of any type
        type: string
        format: binary

requestBody:
  content:
    application/octet-stream:
      schema:
        # 任何类型的二进制文件
        type: string
        format: binary

In addition, specific media types MAY be specified:

此外，可以指定明确的媒体类型：

# multiple, specific media types may be specified:
requestBody:
  content:
      # a binary file of type png or jpeg
    'image/jpeg':
      schema:
        type: string
        format: binary
    'image/png':
      schema:
        type: string
        format: binary        

# 指定多种媒体类型例子:
requestBody:
  content:
      # 一个png或jpeg二进制文件
    'image/jpeg':
      schema:
        type: string
        format: binary
    'image/png':
      schema:
        type: string
        format: binary        

To upload multiple files, a multipart media type MUST be used:

为了同时上传多个文件，必须指定multipart媒体类型：

requestBody:
  content:
    multipart/form-data:
      schema:
        properties:
          # The property name 'file' will be used for all files.
          file:
            type: array
            items:
              type: string
              format: binary

requestBody:
  content:
    multipart/form-data:
      schema:
        properties:
          # 属性名 'file' 会用在所有上传的文件上
          file:
            type: array
            items:
              type: string
              format: binary

To submit content using form url encoding via RFC1866, the following definition may be used:

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

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # complex types are stringified to support RFC 1866
            type: object
            properties: {}

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # 复杂类型需要先按照 RFC 1866 序列化成字符串
            type: object
            properties: {}

In this example, the contents in the requestBody MUST be stringified per RFC1866 when passed to the server. In addition, the address field complex object will be stringified.

在这个示例中，在内容被传送到服务器之前，requestBody中的内容必须(MUST)使用RFC1866中定义的方式字符串化。此外address字段的复杂对象将会被字符串化。

When passing complex objects in the application/x-www-form-urlencoded content type, the default serialization strategy of such properties is described in the Encoding Object's style property as form.

当使用application/x-www-form-urlencoded格式传送复杂对象时, 在Encoding Object的style 属性中定义了默认的序列化策略为form.

It is common to use multipart/form-data as a Content-Type when transferring request bodies to operations. In contrast to 2.0, a schema is REQUIRED to define the input parameters to the operation when using multipart content. This supports complex structures as well as supporting mechanisms for multiple file uploads.

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

When passing in multipart types, boundaries MAY be used to separate sections of the content being transferred — thus, the following default Content-Types are defined for multipart:

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

• If the property is a primitive, or an array of primitive values, the default Content-Type is text/plain
• If the property is complex, or an array of complex values, the default Content-Type is application/json
• If the property is a type: string with format: binary or format: base64 (aka a file object), the default Content-Type is application/octet-stream

• 如果属性是一个原始值或者是一个原始值的数组，那么默认的Content-Type是 text/plain
• 如果属性是复杂对象或者复杂对象的数组，那么默认的Content-Type是application/json
• 如果属性是type: string与format: binary或format: base64(也就是文件对象)的组合，那么默认的Content-Type是 application/octet-stream

Examples:

示例:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # default Content-Type for objects is `application/json`
            type: object
            properties: {}
          profileImage:
            # default Content-Type for string/binary is `application/octet-stream`
            type: string
            format: binary
          children:
            # default Content-Type for arrays is based on the `inner` type (text/plain here)
            type: array
            items:
              type: string
          addresses:
            # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example)
            type: array
            items:
              type: '#/components/schemas/Address'

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # 属性是复杂对象或者复杂对象的数组，那么默认的Content-Type是`application/json`
            type: object
            properties: {}
          profileImage:
            # 属性是`type: string`与`format: binary`或`format: base64`(也就是文件对象)的组合，那么默认的Content-Type是 `application/octet-stream`
            type: string
            format: binary
          children:
            # 属性是一个原始值(此处是string)或者是一个原始值的数组，那么默认的Content-Type是 `text/plain`
            type: array
            items:
              type: string
          addresses:
            # 因为Address是一个复杂对象, 所以这里默认的Content-Type也是`application/json`
            type: array
            items:
              type: '#/components/schemas/Address'

An encoding attribute is introduced to give you control over the serialization of parts of multipart request bodies.
This attribute is only applicable to multipart and application/x-www-form-urlencoded request bodies.

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

A single encoding definition applied to a single schema property.

用于结构(schema)属性的编码定义。

This object MAY be extended with Specification Extensions.

这个对象是个可扩展对象, 可以 (MAY) 按照 Specification Extensions 中的说明进行扩展。

requestBody:
  content:
    multipart/mixed:
      schema:
        type: object
        properties:
          id:
            # default is text/plain
            type: string
            format: uuid
          address:
            # default is application/json
            type: object
            properties: {}
          historyMetadata:
            # need to declare XML format!
            description: metadata in XML format
            type: object
            properties: {}
          profileImage:
            # default is application/octet-stream, need to declare an image type only!
            type: string
            format: binary
      encoding:
        historyMetadata:
          # require XML Content-Type in utf-8 encoding
          contentType: application/xml; charset=utf-8
        profileImage:
          # only accept png/jpeg
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

requestBody:
  content:
    multipart/mixed:
      schema:
        type: object
        properties:
          id:
            # 默认是 text/plain
            type: string
            format: uuid
          address:
            # 默认是 application/json
            type: object
            properties: {}
          historyMetadata:
            # 需要定义成XML媒体类型!
            description: XML格式的元数据
            type: object
            properties: {}
          profileImage:
            # 默认是 application/octet-stream, 需要定义一个图片类型
            type: string
            format: binary
      encoding:
        historyMetadata:
          # 使用utf-8字符串编码的XML媒体类型
          contentType: application/xml; charset=utf-8
        profileImage:
          # 只支持 png/jpeg
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: 当前周期允许的请求速率
              schema:
                type: integer

A container for the expected responses of an operation. The container maps a HTTP response code to the expected response.

Responses对象是一个以响应码为键, 以Response对象为值的映射, 描述了一个操作的一些可能的响应。

The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors.

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

The default MAY be used as a default response object for all HTTP codes that are not covered individually by the specification.

default属性可以(MAY)用来定义一个默认响应, 表示其他未被明确定义的响应码都是返回这个结构。

The Responses Object MUST contain at least one response code, and it SHOULD be the response for a successful operation call.

一个Responses 对象必须(MUST)至少包含一个响应码，而且应该(SHOULD)是成功的响应。