• 最新编辑稿: https://github.com/OAI/OpenAPI-Specification/
• 编辑:
  • Darrel Miller
  • Jeremy Whitlock
  • Marsh Gardiner
  • Mike Ralphson
  • Ron Ratovsky
  • Uri Sarid
• 前编辑:
  • Jason Harmon
  • Tony Tam
• 参与:
  • GitHub OAI/OpenAPI-Specification
  • File a bug
  • Commit history
  • Pull requests

Copyright © 2021 the Linux Foundation

什么是OpenAPI规范？

OpenAPI 规范 (OAS) 为 HTTP APIs 定义了一个标准的、与编程语言无关的接口描述，它允许人类和计算机发现并理解服务的功能，而无需访问源代码、附加文档或检查网络流量。当通过 OpenAPI 正确定义时，消费者可以用最少的实现逻辑理解远程服务并与之交互。与接口描述为低级编程所做的类似，OpenAPI 规范消除了调用服务时的猜测。

1. OpenAPI规范 

1.1 版本3.1.0 

在本文档中，关键字 “MUST”，“MUST NOT”，“REQUIRED”，“SHALL”，“SHALL NOT”，“SHOULD”，“SHOULD NOT”，“RECOMMENDED”，“NOT RECOMMENDED”，“MAY” 和 “OPTIONAL” 应在全部大写的情况下，按照 BCP 14 [RFC2119] [RFC8174] 中的描述进行解释，并且只有在出现在这里时才进行解释。

这个文档使用The Apache License, Version 2.0授权。

2.介绍

OpenAPI规范（OAS）定义了一种标准的、语言无关的HTTP API接口，它允许人类和计算机在没有访问源代码、文档或网络流量检测的情况下发现和理解服务的能力。当正确定义时，消费者可以理解并与远程服务交互，并只需要最少的实现逻辑。

一个 OpenAPI 定义可以被文档生成工具用来显示 API，代码生成工具用来生成各种编程语言的服务器和客户端，测试工具和其他许多用例。

3. 定义 

3.1 OpenAPI 文档 

定义或描述 API 或 API 元素的自包含或复合资源。OpenAPI 文档必须包含至少一个 paths 字段，一个  components 字段或 webhooks 字段。OpenAPI 文档使用并符合 OpenAPI 规范。

3.2 路径模板化 

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

路径中的每个模板表达式必须对应于包含在 Path Item 自身和/或每个路径项的 Operations。例外情况是，如果路径项为空，例如由于 ACL 约束，则不需要匹配的路径参数。

这些路径参数的值不得包含由 [] 描述的任何未转义的“通用语法”字符 [RFC3986]:正斜杠(/)，问号(?)，或者散列(#).

3.3 媒体类型 

媒体类型定义分布在多个资源中。媒体类型定义应该符合 [RFC6838]

可能的媒体类型定义的一些示例:

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

3.4 HTTP 状态代码 

HTTP 状态代码用于指示所执行操作的状态。可用的状态代码由 [RFC7231]和注册状态代码列在 IANA Status Code Registry.

4. 规格 

4.1 版本 

OpenAPI 规范使用主版本.次版本.修订版本号方案进行版本控制。版本号字符串的主版本.次版本部分（例如 3.1）指定 OAS 特性集。修订版本号解决文档中的错误或提供澄清，而不是特性集。支持 OAS 3.1 的工具应该与所有 OAS 3.1.* 版本兼容。修订版本号不应该被工具考虑，例如不会将 3.1.0 和 3.1.1 区分开来。

偶少会在 OAS 的次版本中进行非向后兼容性更改，其影响相对于所提供的好处较低。

兼容 OAS 3. . 的 OpenAPI 文档包含一个必需的 openapi 字段，用于指定其使用的 OAS 版本。

4.2 格式 

OpenAPI 文档符合 OpenAPI 规范本身就是一个 JSON 对象，可以用 JSON 或 YAML 格式表示。

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

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

在规范中所有字段名都是区分大小写的。这包括在映射中用作键的所有字段，除非明确注明键是不区分大小写的。

模式公开了两种字段类型：固定字段，其具有声明的名称，和模式字段，它声明了字段名称的正则表达式模式。

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

为了保持 YAML 和 JSON 格式之间往返的能力，推荐使用 YAML 版本 1.2，以及一些额外的约束：

• 标记必须限制在 JSON 模式规则集允许的标记。
• YAML 映射中使用的键必须限制为标量字符串，由 YAML Failsafe 模式规则集定义。

注意：虽然 API 可以由 YAML 或 JSON 格式的 OpenAPI 文档定义，但 API 请求和响应正文以及其他内容不一定是 JSON 或 YAML。

4.3 文档结构 

OpenAPI 文档可能由单个文档组成，或者由作者决定分成多个相互连接的部分。在后一种情况下，Reference Objects和Schema Object $ref使用了关键字。

它是被推荐的将根 OpenAPI 文档命名为:openapi.json或者openapi.yaml.

4.4 数据类型

OAS 中的数据类型基于 JSON Schema 规范草案 2020-12 支持的类型。请注意，整数也是受支持的类型，它被定义为没有小数或指数部分的 JSON 数字。模型使用 Schema Object 定义，它是 JSON Schema 规范草案 2020-12 的超集。

根据 JSON 模式验证词汇定义，数据类型可以具有可选的修饰符属性：格式。OAS 定义了额外的格式，为基元数据类型提供细节。

OAS 定义的格式是：

4.5 富文本格式 

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

4.6 URIs 的相对参考文献 

除非另有说明，所有属性都可能是由 [RFC3986] 定义的相对引用。

相对引用，包括 Reference Objects、PathItem Object $ref 字段、Link Object operationRef 字段和 Example Object externalValue 字段中的引用，根据 [RFC3986] 使用引用文档作为基本 URI 解析。

如果 URI 包含片段标识符，则应根据引用文档的片段解析机制解析片段。如果引用文档的表示形式是 JSON 或 YAML，则片段标识符应该被解释为 [RFC6901] 中的 JSON-Pointer。

Schema Objects 中的相对引用，包括任何作为 $id 值出现的引用，使用最近父 $id 作为基本 URI，如 JSON Schema 规范草案 2020-12 所述。如果没有父级模式包含 $id，则必须根据 [RFC3986] 确定基本 URI。

4.7 URL 中的相对引用 

除非另有说明，所有属性都可能是由 [RFC3986] 定义的相对引用。除非另有说明，相对引用将使用 Server 对象中定义的 URL 作为基础 URL 解析。请注意，这些本身可能是相对于引用文档的。

4.8 (计划或理论的)纲要 

在以下描述中，如果一个字段没有明确地被 REQUIRED 或用 MUST 或 SHALL 描述，则可以将其视为可选的。

4.8.1 OpenAPI 对象

这是 OpenAPI 文档的根对象。

4.8.1.1 固定字段 

这个对象可以用 Specification Extensions 来扩展。

4.8.2 Info 对象

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

4.8.2.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.2.2信息对象示例

{
  "title": "Sample Pet Store App",
  "summary": "A pet store manager.",
  "description": "This is a sample server for a pet store.",
  "termsOfService": "https://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "https://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
summary: A pet store manager.
description: This is a sample server for a pet store.
termsOfService: https://example.com/terms/
contact:
  name: API Support
  url: https://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

4.8.3 Contact 对象 

公开的 API 的联系信息。

4.8.3.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.3.2联系人对象示例

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

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

4.8.4 License 对象 

公开的 API 的许可证信息。

4.8.4.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.4.2许可证对象示例

{
  "name": "Apache 2.0",
  "identifier": "Apache-2.0"
}

name: Apache 2.0
identifier: Apache-2.0

4.8.5 Server 对象 

表示服务器的对象。

4.8.5.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.5.2服务器对象示例

单个服务器将被描述为：

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

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

下面显示了如何描述多个服务器，例如，在 OpenAPI 对象的servers：

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

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

下面显示了如何将变量用于服务器配置：

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

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

4.8.6 Server Variable 对象 

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

4.8.6.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.7 Components对象 

为 OAS 的不同方面保存一组可重用对象。components 对象中定义的所有对象对 API 都没有影响，除非从 components 对象外部的属性中明确引用它们。

4.8.7.1固定字段§ 

这个对象可以用 Specification Extensions 来扩展。

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

字段名称示例：

User
User_1
User_Name
user-name
my.org.User

4.8.7.2组件对象示例

"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": "https://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: https://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets

4.8.8 Paths 对象 

保存各个端点及其操作的相对路径。路径附加到 URL Server Object以构建完整的 URL。由于访问控制列表 (ACL) 约束，路径可能为空。

4.8.8.1图案字段

这个对象可以用 Specification Extensions 来扩展。

4.8.8.2路径模板匹配

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

  /宠物/{petId}
  /宠物/我的

以下路径被视为相同且无效：

  /宠物/{petId}
  /宠物的名字}

以下可能会导致不明确的解决方案：

  /{实体}/我
  /书籍/{id}

4.8.8.3路径对象示例

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

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

4.8.9 Path Item 对象

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

4.8.9.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.9.2路径项对象示例

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

4.8.10 Operation 对象 

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

4.8.10.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.10.2操作对象示例

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

4.8.11 External Documentation 对象 

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

4.8.11.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.11.2外部文档对象示例

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

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

4.8.12 Parameter 对象 

描述单个操作参数。

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

4.8.12.1参数位置

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

• path - 与 Path Templating 一起使用，其中参数值实际上是操作 URL 的一部分。这不包括 API 的主机或基本路径。例如，在 中/items/{itemId}，路径参数为itemId。
• query - 附加到 URL 的参数。例如，在 中/items?id=###，查询参数是id。
• header - 预期作为请求一部分的自定义标头。请注意， [RFC7230] 声明标头名称不区分大小写。
• cookie - 用于将特定的 cookie 值传递给 API。

4.8.12.2固定字段

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

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

4.8.12.3样式值

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

4.8.12.4样式示例

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

   字符串 -> “蓝色”
   array -> [ "blue" , "black" , "brown" ] 
   object -> { "R": 100 , "G" : 200 , "B" : 150 }

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

这个对象可以用 Specification Extensions 来扩展。

4.8.12.5参数对象示例

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

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

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

字符串值的路径参数：

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

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

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

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

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

一个自由形式的查询参数，允许特定类型的未定义参数：

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

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

content用于定义序列化的复杂参数：

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

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

4.8.13 Request Body 对象 

描述单个请求正文。

4.8.13.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.13.2请求正文示例

具有引用模型定义的请求正文。

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

一个主体参数，它是一个字符串值数组：

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

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

4.8.14 Media Type 对象 

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

4.8.14.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.14.2媒体类型示例

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

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

4.8.14.3文件上传注意事项

与 2.0 规范相比，fileOpenAPI 中的输入/输出内容使用与任何其他模式类型相同的语义进行描述。

与 3.0 规范相比，format 关键字对模式的内容编码没有影响。JSON Schema 提供了一个 contentEncoding 关键字，可用于 Content-Encoding 为模式指定。该 contentEncoding 关键字支持 [RFC4648] 中定义的所有编码，包括 “base64” 和 “base64url”，以及 [RFC2045] 中的 “quoted-printable”。关键字指定的contentEncoding 编码独立 Content-Type 于请求或响应中的标头指定的编码或多部分主体的元数据 - 当两者都存在时，contentEncoding 首先应用在中指定的编码，然后应用 Content-Type 标头中指定的编码。

JSON Schema 也提供了一个 contentMediaType 关键字。然而，当媒体类型已经由 Media Type Object 的键或 Encoding Object 的 contentType 字段指定时，如果存在 contentMediaType 关键字，则应该忽略它。

例子：

以二进制（八位字节流）传输的内容可​​以省略schema：

# a PNG image as a binary file:
content:
    image/png: {}

# an arbitrary binary file:
content:
    application/octet-stream: {}

使用 base64 编码传输的二进制内容：

content:
    image/png:
        schema:
            type: string
            contentMediaType: image/png
            contentEncoding: base64

注意，Content-Type 仍为 image/png，描述有效负载的语义。JSON Schema 类型和 contentEncoding 字段解释有效负载以文本形式传输。JSON Schema contentMediaType 在技术上是冗余的，但可以被不知道OpenAPI上下文的 JSON Schema 工具使用。

这些示例适用于文件上传的输入有效负载或响应有效负载。

requestBody用于在操作中提交文件的POST可能类似于以下示例：

requestBody:
  content:
    application/octet-stream: {}

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

# multiple, specific media types may be specified:
requestBody:
  content:
    # a binary file of type png or jpeg
    image/jpeg: {}
    image/png: {}

要上传多个文件，必须multipart使用媒体类型：

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

如以下部分multipart/form-data所示，空模式items表示媒体类型为application/octet-stream.

4.8.14.4支持 x-www-form-urlencoded 请求体

要通过 [RFC1866] 使用表单 url 编码提交内容，可以使用以下定义：

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

在此示例中，当传递到服务器时，requestBody 必须按照  [RFC1866 ] 对内容进行字符串化。此外，address字段复杂对象将被字符串化。

在application/x-www-form-urlencoded内容类型中传递复杂对象时，此类属性的默认序列化策略在 的属性中Encoding Object描述style为form.

4.8.14.5multipart内容的特殊注意事项

当将请求体传输到操作时，使用 multipart/form-data 作为 Content-Type 是很常见的。与 2.0 版本不同的是，在使用 multipart 内容时，操作需要定义输入参数。这支持复杂的结构以及支持多个文件上传的机制。

在 multipart/form-data 请求体中，每个模式属性或模式数组属性的每个元素都在有一个由 [RFC7578] 定义的内部标题的有效载荷中占有一部分。可以在关联的编码对象中指定multipart/form-data 请求体的每个属性的序列化策略。

传入multipart类型时，边界可以用于分隔正在传输的内容的各个部分——因此，Content-Type为 定义了以下默认值multipart：

• 如果该属性是原始值或原始值数组，则默认的 Content-Type 是text/plain
• 如果属性很复杂，或者是复杂值的数组，则默认的 Content-Type 是application/json
• 如果属性是类型:带有 contentEncoding 的字符串，则默认的 Content-Type 是application/octet-stream

根据 JSON Schema 规范，如果 contentMediaType 没有 contentEncoding，则视为 contentEncoding: identity 存在。这对嵌入文本文档（如text/html）到 JSON 字符串中很有用，但对于 multipart/form-data 部分则无用，因为它只会将文档视为 text/plain，而不是它的实际媒体类型。如果不需要 contentEncoding，请使用 Encoding Object。

例子：

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:
            # Content-Type for application-level encoded resource is `text/plain`
            type: string
            contentMediaType: image/png
            contentEncoding: base64
          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: object
              $ref: '#/components/schemas/Address'

引入了一个 encoding 属性来让您控制 multipart 请求主体部分的序列化。此属性仅适用于 multipart 和 application/x-www-form-urlencoded 请求主体。

4.8.15 Encoding 对象 

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

4.8.15.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.15.2编码对象示例

requestBody:
  content:
    multipart/form-data:
      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: {}
      encoding:
        historyMetadata:
          # require XML Content-Type in utf-8 encoding
          contentType: application/xml; charset=utf-8
        profileImage:
          # only accept png/jpeg
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

4.8.16 Responses 对象 

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

文档不一定涵盖所有可能的 HTTP 响应代码，因为它们可能无法提前获知。但是，文档应涵盖成功的操作响应和任何已知错误。

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

Responses Object 必须包含至少一个响应代码，如果只提供一个响应代码，它应该是成功操作调用的响应。

4.8.16.1固定字段

4.8.16.2图案字段

这个对象可以用 Specification Extensions 来扩展。

4.8.16.3响应对象示例

成功操作的 200 响应和其他默认响应（暗示错误）：

{
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}

'200':
  description: a pet to be returned
  content: 
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'
default:
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorModel'

4.8.17 Response 对象 

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

4.8.17.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.17.2响应对象示例

复杂类型数组的响应：

{
  "description": "A complex object array response",
  "content": {
    "application/json": {
      "schema": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/VeryComplexType"
        }
      }
    }
  }
}

description: A complex object array response
content: 
  application/json:
    schema: 
      type: array
      items:
        $ref: '#/components/schemas/VeryComplexType'

字符串类型的响应：

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      }
    }
  }

}

description: A simple string response
content:
  text/plain:
    schema:
      type: string

带有标题的纯文本响应：

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

description: A simple string response
content:
  text/plain:
    schema:
      type: string
    example: 'whoa!'
headers:
  X-Rate-Limit-Limit:
    description: The number of allowed requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Remaining:
    description: The number of remaining requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Reset:
    description: The number of seconds left in the current period
    schema:
      type: integer

没有返回值的响应：

{
  "description": "object created"
}

description: object created

4.8.18 Callback 对象

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

要描述独立于另一个 API 调用的来自 API 提供者的传入请求，请使用该webhooks字段。

4.8.18.1图案字段

这个对象可以用 Specification Extensions 来扩展。

4.8.18.2键表达式

标识路径项对象的键是一个运行时表达式，可以在运行时 HTTP 请求/响应的上下文中求值，以确定用于回调请求的 URL。一个简单的例子可能是 $request.body#/url。然而，使用运行时表达式可以访问完整的 HTTP 消息。这包括访问 JSON 指针 [RFC6901] 可以引用的任何部分。

例如，给定以下 HTTP 请求：

POST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 187

{
  "failedUrl" : "https://clientdomain.com/failed",
  "successUrls" : [
    "https://clientdomain.com/fast",
    "https://clientdomain.com/medium",
    "https://clientdomain.com/slow"
  ] 
}

201 Created
Location: https://example.org/subscription/1

以下示例展示了各种表达式的计算方式，假设回调操作有一个名为 的路径参数eventType和一个名为 的查询参数queryUrl。

4.8.18.3回调对象示例

以下示例使用用户提供的queryUrl查询字符串参数来定义回调 URL。这是一个示例，说明如何使用回调对象来描述与订阅操作一起使用的 WebHook 回调，以启用对 WebHook 的注册。

myCallback:
  '{$request.query.queryUrl}':
    post:
      requestBody:
        description: Callback payload
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

以下示例显示了一个回调，其中服务器是硬编码的，但查询字符串参数是从请求正文中的id和email属性填充的。

transactionCallback:
  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
    post:
      requestBody:
        description: Callback payload
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

4.8.19 Example 对象

4.8.19.1固定字段

这个对象可以用 Specification Extensions来扩展。

在所有情况下，示例值都应与其关联值的类型模式兼容。工具实现可以选择自动验证兼容性，如果不兼容则拒绝示例值。

4.8.19.2示例对象示例

在请求正文中：

requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples: 
        foo:
          summary: A foo example
          value: {"foo": "bar"}
        bar:
          summary: A bar example
          value: {"bar": "baz"}
    'application/xml':
      examples: 
        xmlExample:
          summary: This is an example in XML
          externalValue: 'https://example.org/examples/address-example.xml'
    'text/plain':
      examples:
        textExample: 
          summary: This is a text example
          externalValue: 'https://foo.bar/examples/address-example.txt'

在一个参数中：

parameters:
  - name: 'zipCode'
    in: 'query'
    schema:
      type: 'string'
      format: 'zip-code'
    examples:
      zip-example: 
        $ref: '#/components/examples/zip-example'

在回应中：

responses:
  '200':
    description: your car appointment has been booked
    content: 
      application/json:
        schema:
          $ref: '#/components/schemas/SuccessResponse'
        examples:
          confirmation-success:
            $ref: '#/components/examples/confirmation-success'

4.8.20 Link 对象

Link object表示响应的可能设计时链接。链接的存在并不能保证调用者能够成功调用它，而是它提供了响应和其他操作之间的已知关系和遍历机制。

与动态链接（即响应负载中提供的链接）不同，OAS 链接机制不需要运行时响应中的链接信息。

为了计算链接并提供执行它们的指令，运行时表达式用于访问操作中的值并在调用链接操作时将它们用作参数。

4.8.20.1固定字段

这个对象可以用 Specification Extensions 来扩展。

链接操作必须使用 operationRef 或 operationId 中的一个进行标识。如果是 operationId，则它必须是唯一的，并在 OAS 文档的范围内解析。由于名称冲突的可能性，建议在具有外部引用的 OpenAPI 文档中使用 operationRef 语法。

4.8.20.2示例

从请求操作计算链接，其中$request.path.id用于将请求参数传递给链接操作。

paths:
  /users/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: the user identifier, as userId 
      schema:
        type: string
    get:
      responses:
        '200':
          description: the user being returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid: # the unique user id
                    type: string
                    format: uuid
          links:
            address:
              # the target link operationId
              operationId: getUserAddress
              parameters:
                # get the `id` field from the request path parameter named `id`
                userId: $request.path.id
  # the path item of the linked operation
  /users/{userid}/address:
    parameters:
    - name: userid
      in: path
      required: true
      description: the user identifier, as userId 
      schema:
        type: string
    # linked operation
    get:
      operationId: getUserAddress
      responses:
        '200':
          description: the user's address

当运行时表达式无法计算时，不会将任何参数值传递给目标操作。

来自响应主体的值可用于驱动链接操作。

links:
  address:
    operationId: getUserAddressByUUID
    parameters:
      # get the `uuid` field from the `uuid` field in the response body
      userUuid: $response.body#/uuid

客户自行决定是否访问所有链接。仅通过关系的存在来保证权限或成功调用该链接的能力。

4.8.20.3 OperationRef 示例

由于operationId 可能无法引用（这operationId是操作对象中的可选字段），因此也可以通过亲戚进行引用operationRef：

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

或绝对operationRef：

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

请注意，在使用 时operationRef，转义的正斜杠在使用 JSON 引用时是必需的。

4.8.20.4运行时表达式 

运行时表达式允许根据仅在实际 API 调用中的 HTTP 消息中可用的信息来定义值。链接对象和回调对象使用此机制。

运行时表达式由以下ABNF语法定义

      expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
      source = ( header-reference / query-reference / path-reference / body-reference )
      header-reference = "header." token
      query-reference = "query." name  
      path-reference = "path." name
      body-reference = "body" ["#" json-pointer ]
      json-pointer    = *( "/" reference-token )
      reference-token = *( unescaped / escaped )
      unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
         ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
      escaped         = "~" ( "0" / "1" )
        ; representing '~' and '/', respectively
      name = *( CHAR )
      token = 1*tchar
      tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
        "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA

此处，json-pointer 取自  [RFC6901]、char  [RFC7159] 和 token [RFC7230]。

name标识符区分大小写，反之token则不区分大小写。

下表提供了运行时表达式的示例以及它们在值中的使用示例：

4.8.20.5示例

运行时表达式保留引用值的类型。{}可以通过用大括号将表达式括起来，将表达式嵌入到字符串值中。

4.8.21 Header 对象 

Header 对象遵循 Parameter 对象的结构，但有以下变化：

1. name 不得指定，它在相应的 headers 地图中给出。
2. in 不得指定，它隐含在 header.
3. 受位置影响的所有特征必须适用于 header（例如，style）的位置。

4.8.21.1标头对象示例

类型的简单标头integer：

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

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

4.8.22 Tag 对象 

将元数据添加到 Operation Object 使用的单个标记。在操作对象实例中定义的每个标签都不是强制性的。

4.8.22.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.22.2标签对象示例

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

name: pet
description: Pets operations

4.8.23 Reference 对象

一个简单的对象，允许在内部和外部引用 OpenAPI 文档中的其他组件。

$ref字符串值包含一个 URI  [RFC3986]，它标识被引用值的位置。

请参阅解析 Relative References 的规则。

4.8.23.1固定字段

该对象不能用附加属性扩展，任何添加的属性都应被忽略。

请注意，对其他属性的此限制是 Reference Objects 和包含 $ref 关键字的 Schema Objects 之间的差异。

4.8.23.2引用对象示例

{
	"$ref": "#/components/schemas/Pet"
}

$ref: '#/components/schemas/Pet'

4.8.23.3相关模式文档示例

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

$ref: Pet.yaml

4.8.23.4具有嵌入式模式示例的相关文档

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

$ref: definitions.yaml#/Pet

4.8.24 Schema 对象 

Schema 对象允许定义输入和输出数据类型。这些类型可以是对象，也可以是基元和数组。该对象是JSON Schema Specification Draft 2020-12的超集。

有关属性的更多信息，请参阅JSON Schema Core和JSON Schema Validation。

除非另有说明，否则属性定义遵循 JSON Schema 的定义，并且不添加任何额外的语义。在 JSON Schema 指示行为由应用程序定义的地方（例如注释），OAS 还将语义定义推迟到使用 OpenAPI 文档的应用程序。

4.8.24.1属性

OpenAPI Schema 对象方言定义为需要 OAS 基础词汇表，此外还需要 JSON Schema 草案 2020-12 一般用途元模式中指定的词汇 。

此版本规范的 OpenAPI 架构对象方言由 URI https://spec.openapis.org/oas/3.1/dialect/base（ “OAS 方言架构 ID”）标识。

以下属性取自 JSON Schema 规范，但它们的定义已由 OAS 扩展：

• description - CommonMark 语法 可以用于富文本表示。
• format - 有关更多详细信息，请参阅数据类型格式。在依赖 JSON Schema 定义的格式的同时，OAS 提供了一些额外的预定义格式。

除了包含 OAS 方言的 JSON 架构属性之外，Schema 对象还支持来自任何其他词汇表的关键字，或完全任意的属性。

OpenAPI 规范的基本词汇表由以下关键字组成：

4.8.24.2固定字段

该对象可以使用 Specification Extensions 进行扩展，但如上所述，附加属性可以省略x-该对象中的前缀。

4.8.24.2.1组合和继承（多态） 

OpenAPI 规范允许使用 JSON Schema 的 allOf 属性组合和扩展模型定义，实际上提供了模型组合。allOf 接受一组独立验证但共同组成单个对象的对象定义。

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

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

4.8.24.2.2 XML 建模

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

4.8.24.2.3指定模式方言

工具需要能够确定任何给定资源希望使用的方言或元模式：JSON Schema Core、JSON Schema验证、OpenAPI Schema方言或某些自定义元模式。

在任何根 Schema 对象中可能存在 $schema 关键字，如果存在，必须使用它来确定处理该模式时应使用的方言。这允许使用符合其他 JSON 模式草案的 Schema 对象，而不是默认的 Draft 2020-12 支持。工具必须支持 OAS 方言模式 ID，并可能支持 $schema 的其他值。

为了允许在 OAS 文档中包含的所有 Schema 对象中使用不同的默认 $schema 值，可以在 OpenAPI 对象中设置jsonSchemaDialect 值。如果未设置此默认值，则必须在这些 Schema 对象中使用 OAS 方言模式 ID。 Schema 对象中的 $schema 值始终优先于任何默认值。

当从非 OAS 文档的外部资源（例如，纯 JSON 模式资源）引用 Schema 对象时，该资源中$schema模式的关键字值必须遵循JSON 模式规则。

4.8.24.3模式对象示例

4.8.24.3.1原始样本

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

type: string
format: email

4.8.24.3.2简单模型

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

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

4.8.24.3.3具有地图/字典属性的模型

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

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

type: object
additionalProperties:
  type: string

对于字符串到模型的映射：

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

type: object
additionalProperties:
  $ref: '#/components/schemas/ComplexModel'

4.8.24.3.4示例模型

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

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

4.8.24.3.5具有组合的模型

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

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

4.8.24.3.6支持多态性的模型

{
  "components": {
    "schemas": {
      "Pet": {
        "type": "object",
        "discriminator": {
          "propertyName": "petType"
        },
        "properties": {
          "name": {
            "type": "string"
          },
          "petType": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "petType"
        ]
      },
      "Cat": {
        "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "huntingSkill": {
                "type": "string",
                "description": "The measured skill for hunting",
                "default": "lazy",
                "enum": [
                  "clueless",
                  "lazy",
                  "adventurous",
                  "aggressive"
                ]
              }
            },
            "required": [
              "huntingSkill"
            ]
          }
        ]
      },
      "Dog": {
        "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "packSize": {
                "type": "integer",
                "format": "int32",
                "description": "the size of the pack the dog is from",
                "default": 0,
                "minimum": 0
              }
            },
            "required": [
              "packSize"
            ]
          }
        ]
      }
    }
  }
}

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
      properties:
        name:
          type: string
        petType:
          type: string
      required:
      - name
      - petType
    Cat:  ## "Cat" will be used as the discriminator value
      description: A representation of a cat
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        properties:
          huntingSkill:
            type: string
            description: The measured skill for hunting
            enum:
            - clueless
            - lazy
            - adventurous
            - aggressive
        required:
        - huntingSkill
    Dog:  ## "Dog" will be used as the discriminator value
      description: A representation of a dog
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        properties:
          packSize:
            type: integer
            format: int32
            description: the size of the pack the dog is from
            default: 0
            minimum: 0
        required:
        - packSize

4.8.25 Discriminator 对象 

当请求主体或响应有效负载可能是多种不同模式之一时，discriminator可以使用对象来帮助序列化、反序列化和验证。鉴别器是模式中的特定对象，用于根据与其关联的值通知文档的消费者替代模式。

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

4.8.25.1固定字段

这个对象可以用 Specification Extensions 来扩展。

鉴别器对象仅在使用 oneOf，anyOf，allOf 等复合关键字时是合法的。

在 OAS 3.0 中，响应负载可以被描述为任意数量类型中的一种：

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

这意味着负载必须通过验证与 Cat，Dog 或 Lizard 描述的模式之一完全匹配。在这种情况下，鉴别器可能充当“提示”，缩短验证和匹配模式的选择，这可能是一项昂贵的操作，具体取决于模式的复杂性。我们可以描述哪个字段告诉我们使用哪个模式：

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

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

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

将指示 Cat 模式与此有效负载结合使用。

在鉴别器字段的值与模式名称不匹配或隐式映射不可能的情况下，可以 mapping 使用可选定义：**

MyResponseType:
  oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
  - $ref: '#/components/schemas/Lizard'
  - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json'
  discriminator:
    propertyName: petType
    mapping:
      dog: '#/components/schemas/Dog'
      monster: 'https://gigantic-server.com/schemas/Monster/schema.json'

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

当与anyOf构造结合使用时，使用鉴别器可以避免多个模式可能满足单个有效负载的歧义。

在oneOf和anyOf用例中，所有可能的模式都必须明确列出。为了避免冗余，可以将鉴别器添加到父模式定义中，并且allOf构造中包含父模式的所有模式都可以用作替代模式。

例如：

components:
  schemas:
    Pet:
      type: object
      required:
      - petType
      properties:
        petType:
          type: string
      discriminator:
        propertyName: petType
        mapping:
          dog: Dog
    Cat:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Cat`
        properties:
          name:
            type: string
    Dog:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Dog`
        properties:
          bark:
            type: string
    Lizard:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Lizard`
        properties:
          lovesRocks:
            type: boolean

像这样的有效载荷：

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

将指示使用的Cat架构。同样这个模式：

{
  "petType": "dog",
  "bark": "soft"
}

Dog由于mapping元素中的定义，将映射到。

4.8.26 XML 对象 

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

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

4.8.26.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.26.2 XML 对象示例

XML 对象定义的示例包含在带有它的 XML 表示示例的模式对象的属性定义中。

4.8.26.2.1无 XML 元素

基本字符串属性：

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

animals:
  type: string

<animals>...</animals>

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

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

animals:
  type: array
  items:
    type: string

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

4.8.26.2.2 XML 名称替换

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

animals:
  type: string
  xml:
    name: animal

<animal>...</animal>

4.8.26.2.3 XML 属性、前缀和命名空间

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

{
  "Person": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int32",
        "xml": {
          "attribute": true
        }
      },
      "name": {
        "type": "string",
        "xml": {
          "namespace": "https://example.com/schema/sample",
          "prefix": "sample"
        }
      }
    }
  }
}

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

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

4.8.26.2.4 XML 数组

更改元素名称：

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

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

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

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

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

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

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

即使数组被包装，如果没有显式定义名称，内部和外部也会使用相同的名称：

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

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

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

为了克服上面示例中的命名问题，可以使用以下定义：

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

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

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

影响内部和外部名称：

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

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

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

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

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

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

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

4.8.27 Security Scheme 对象 

定义操作可以使用的安全方案。

支持的方案是 HTTP 身份验证、API 密钥（作为标头、cookie 参数或作为查询参数）、双向 TLS（使用客户端证书）、OAuth2 的常见流程（隐式、密码、客户端凭据和授权代码）作为在  [RFC6749] 和 OpenID Connect Discovery 中定义。请注意，自 2020 年起，隐式流程将被 OAuth 2.0 Security Best Current Practice 弃用。对于大多数用例，建议使用 PKCE 的授权代码授予流程。

4.8.27.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.27.2安全方案对象示例

4.8.27.2.1基本身份验证示例

{
  "type": "http",
  "scheme": "basic"
}

type: http
scheme: basic

4.8.27.2.2 API 密钥示例

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

type: apiKey
name: api_key
in: header

4.8.27.2.3 JWT 不记名样本

{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT",
}

type: http
scheme: bearer
bearerFormat: JWT

4.8.27.2.4隐式 OAuth2 示例

{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

type: oauth2
flows: 
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

4.8.28 OAuth Flows 对象 

允许配置支持的 OAuth 流程。

4.8.28.1固定字段§ 

这个对象可以用 Specification Extensions 来扩展。

4.8.29 OAuth Flow 对象 

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

4.8.29.1固定字段

这个对象可以用 Specification Extensions 来扩展。

4.8.29.2 OAuth 流对象示例

{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    },
    "authorizationCode": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "tokenUrl": "https://example.com/api/oauth/token",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

type: oauth2
flows: 
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets
  authorizationCode:
    authorizationUrl: https://example.com/api/oauth/dialog
    tokenUrl: https://example.com/api/oauth/token
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets 

4.8.30 Security Requirement 对象 

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

包含多个方案的安全要求对象要求必须满足所有方案才能授权请求。这支持需要多个查询参数或 HTTP 标头来传达安全信息的场景。

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

4.8.30.1图案字段

|

4.8.30.2安全需求对象示例

4.8.30.2.1非 OAuth2 安全要求

{
  "api_key": []
}

api_key: []

4.8.30.2.2 OAuth2 安全要求

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

petstore_auth:
- write:pets
- read:pets

4.8.30.2.3可选的 OAuth2 安全性

可选的 OAuth2 安全性将在 OpenAPI 对象或操作对象中定义：

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

security:
  - {}
  - petstore_auth:
    - write:pets
    - read:pets

4.9 Specification Extensions 

虽然 OpenAPI 规范试图适应大多数用例，但可以添加额外的数据以在某些点扩展规范。

扩展属性被实现为总是以 . 为前缀的模式化字段"x-"。

| 字段模式 | 类型 | 描述 | | ------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ^x- | Any | 允许对 OpenAPI 模式进行扩展。字段名必须以 开头x-，例如x-internal-id. 以x-oai-和和 x-oas-开头的字段名称是 OpenAPI Initiative 定义的用途保留使用。该值可以为 null、原始类型、数组或对象。 |

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

4.10 Security Filtering 

OpenAPI 规范中的某些对象可能被声明为空，甚至可能被完全删除，尽管它们是 API 文档的核心。

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

两个例子：

1. Paths 对象可能存在但是为空。这可能会让阅读者感到困惑，但它告诉阅读者他们已经到达了正确的位置，但无法访问任何文档。他们仍然可以访问 Info 对象，其中可能包含有关身份验证的其他信息。
2. Path Item 对象可能为空。在这种情况下，阅读者将知道该路径存在，但无法看到其操作或参数。这与将路径从 Paths 对象中隐藏是不同的，因为用户将知道它的存在。这允许文档提供者精细控制阅读者可以看到的内容。

5.附录 A：修订历史 

A.参考文献

A.1规范性引用文件

• [RFC1866]

• Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866

• [RFC2045]

• Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2045

• [RFC2119]

• Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119

• [RFC3986]

• Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986

• [RFC4648]

• The Base16, Base32, and Base64 Data Encodings. S. Josefsson. IETF. October 2006. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4648

• [RFC6570]

• URI Template. J. Gregorio; R. Fielding; M. Hadley; M. Nottingham; D. Orchard. IETF. March 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6570

• [RFC6749]

• The OAuth 2.0 Authorization Framework. D. Hardt, Ed.. IETF. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6749

• [RFC6838]

• Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838

• [RFC6901]

• JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901

• [RFC7159]

• The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159

• [RFC7230]

• Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html

• [RFC7231]

• Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html

• [RFC7235]

• Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html

• [RFC7578]

• Returning Values from Forms: multipart/form-data. L. Masinter. IETF. July 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7578

• [RFC8174]

• Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174